GitHub.com provider

Configure GitHub.com mirrors

Register an existing repository or create one through GitHub.com, then let Redmine browse a credential-safe local bare mirror.

Server configuration

Configure a writable mirror root and provide GitHub API credentials through environment variables. Existing public repositories can be mirrored from their full URL without an API token; creating repositories, accessing private repositories, testing credentials, and registering webhooks require a token.

export REDMINE_SCM_GITHUB_API_TOKEN='your-token'
export REDMINE_SCM_GITHUB_ORGANIZATION='optional-organization'

Credential precedence: a repository-specific token stored through Redmine's encrypted credential mechanism overrides the server environment token.

Add the provider configuration

Copy plugins/redmine_scm/config/scm.yml.sample to config/scm.yml in the Redmine root and adapt the production section. The mirror root must exist, be writable by the Redmine service account and have enough space for bare Git repositories.

production:
  github:
    path: /var/lib/redmine/github_mirrors
    minimum_free_space_mb: 1024
    clone_protocol: ssh
    api:
      token: <%= ENV['REDMINE_SCM_GITHUB_API_TOKEN'] %>
      organization: <%= ENV['REDMINE_SCM_GITHUB_ORGANIZATION'] %>
      register_hook: true
      open_timeout: 5
      timeout: 15
    options:
      private: true

Use clone_protocol: ssh when the Redmine service account has a deploy key and GitHub.com's host key in known_hosts. Use HTTPS when your operating model prefers token-based transport. Restart every Redmine web and background process after changing environment variables or scm.yml.

Create or reuse a repository

Enter a full GitHub.com URL to mirror an existing repository, or enter a repository name to create it in the configured account or organization. Test the connection before saving when credentials are required.

SCM Creator GitHub.com repository and mirror configuration form — DesktopRepository creation, connection testing and webhook registration.

GitHub.com mirror configuration form in a narrow Redmine layout — ResponsiveThe same protected controls on a narrow layout.

Choose the correct setup path

Existing public repository

Input: complete GitHub.com repository URL

Credentials: none for cloning; API features still require a token.

Existing private repository

Input: complete GitHub.com repository URL

Credentials: token or SSH access for the Redmine service account.

Create a new repository

Input: repository name and optional organization

Credentials: token with permission to create the repository.

Register a push webhook

Input: enable webhook registration

Credentials: token with repository administration permission.

Before saving, test the connection and verify that the reported account or organization is the intended target. After saving, open the Repository tab and perform one manual refresh. A failed test normally points to the token, organization, TLS connectivity or requested GitHub permission; a failed mirror refresh normally points to Git transport, SSH host keys, filesystem access or free disk space.

Operational behavior

Mirror creation and manual refresh are synchronous; large repositories may keep the web request open.
Each mirror has a nonblocking refresh lock and optional minimum-free-space check.
Signed webhooks use a per-repository secret and verify X-Hub-Signature-256.
Deleting the Redmine repository removes only the local mirror and registration, never the remote GitHub repository.

Provider scope: this integration supports GitHub.com only. It does not support GitLab, GitHub Enterprise Server or arbitrary Git hosting services.

Need help diagnosing a failed test, webhook or refresh? Continue with the GitHub.com troubleshooting checklist.