Redmine

SCM Creator¶

SCM Creator creates repositories from Redmine project settings and registers them with the project. It supports local Git, Subversion, Mercurial and Bazaar repositories as well as GitHub.com repositories backed by a local bare mirror.

This Redmine 6 release is a modernized continuation of the original SCM Creator plugin by Andriy Lesyuk. It does not modify Redmine core files.

Current version: 2.2.1

Compatibility¶

• Redmine 6.0.x
• Redmine 6.1.x

The plugin requires the command-line client for each enabled SCM and a repository root writable by the Redmine application user. GitHub support requires Octokit 10 and Faraday Retry 2.2, declared in the bundled Gemfile.

Main features¶

• Creates and registers local Git repositories
• Creates and registers local Subversion repositories
• Creates and registers local Mercurial repositories
• Creates and registers local Bazaar repositories
• Creates GitHub.com repositories and maintains local bare mirrors for Redmine
• Registers existing public GitHub repositories without requiring an API token
• Supports private GitHub repositories with repository-specific or environment-provided tokens
• Reuses an accessible existing GitHub repository instead of attempting duplicate creation
• Tests GitHub credentials and repository access from the repository form
• Shows mirror health, local size, last successful fetch and the most recent error
• Provides a protected manual mirror refresh action with per-mirror locking
• Supports signed per-repository GitHub push webhooks
• Supports optional repository creation during project creation
• Supports lifecycle scripts before and after repository creation or deletion
• Renames managed repositories safely after project identifier changes
• Provides configurable repository limits and managed deletion behavior

Local repository creation¶

Users with Redmine's Manage repository permission can create a configured repository from Project > Settings > Repositories. Repository storage paths, binaries and displayed external URLs are configured centrally in config/scm.yml.

The plugin creates repository storage but does not publish repositories over HTTP, SSH or Subversion DAV. The administrator must configure the appropriate Git, SSH, Apache, Nginx or Subversion service separately.

GitHub.com mirrors¶

Existing public GitHub repositories can be registered from a full repository URL without an API token. Creating repositories, accessing private repositories, testing API credentials and registering webhooks require a suitable GitHub token.

A token entered for a repository takes precedence over the REDMINE_SCM_GITHUB_API_TOKEN environment variable. Repository credentials use Redmine's encrypted repository credential storage. HTTPS credentials are passed to Git through command-scoped environment configuration and are not stored in mirror remote URLs or placed in command arguments.

Each GitHub repository uses its own webhook secret. Incoming push requests must pass an X-Hub-Signature-256 check before the mirror is refreshed. The legacy global Redmine repository-management key is not used for webhook authentication.

Mirror creation and manual refresh run synchronously in the Redmine request. Creating or refreshing a very large mirror can therefore keep the request open for a long time. Administrators should plan storage capacity and request timeouts accordingly.

Filesystem safety¶

Managed repository paths must resolve to one direct child below the configured provider root. SCM Creator rejects traversal, nested unmanaged paths and paths outside that root. GitHub mirror creation also checks root write access and can enforce a configurable minimum-free-space threshold.

License and maintainers¶

SCM Creator is distributed under the GNU General Public License version 2 (GPL-2.0-only).

• Original author: Andriy Lesyuk
• Current Redmine 6 maintainer: www.SaaS-Secure.com, S. Ruttloff
• Website: https://www.saas-secure.com
• Contact: info@saas-secure.com

Installation Notes¶

Requirements¶

• Redmine 6.0 or 6.1
• The command-line client for every enabled SCM provider
• A repository root writable by the Redmine application user for every enabled provider
• Git and the bundled Ruby dependencies when GitHub.com support is enabled
• A prepared Redmine database backup before installation or upgrade

Installation¶

1. Download the release archive.
2. Extract it into the Redmine plugins directory so the final path is:

plugins/redmine_scm

1. From the Redmine root directory, install the plugin's Ruby dependencies:

bundle install

1. Run the plugin migration:

bundle exec rake redmine:plugins:migrate RAILS_ENV=production

1. Copy the sample configuration to the Redmine configuration directory:

cp plugins/redmine_scm/config/scm.yml config/scm.yml

If config/scm.yml already exists, back it up and merge the SCM Creator settings instead of overwriting it.

1. Edit the production section in config/scm.yml. Configure only the providers that should be available and verify every repository path and executable path.
2. Remove or replace the sample pre_create, post_create, pre_delete and post_delete script paths. Configured lifecycle scripts must exist and be executable.
3. Create the configured repository roots and grant write access to the operating-system account running Redmine.
4. Restart Redmine.
5. Open Administration > Settings > Repositories and enable the required SCM providers.
6. Verify that the appropriate project roles have Redmine's Manage repository permission.

Minimal local Git example¶

The displayed url is the external URL used by clients. SCM Creator does not configure or operate the external Git HTTP or SSH service.

production:
  deny_delete: false
  auto_create: false
  git:
    path: /var/lib/git
    git: /usr/bin/git
    options: --bare
    url: ssh://git@example.org/
    git_ext: true

Create the repository root with permissions suitable for the Redmine application user, for example:

sudo mkdir -p /var/lib/git
sudo chown redmine:redmine /var/lib/git

Adapt the account and group names to the local Redmine deployment.

GitHub.com setup¶

Provide API credentials through the Redmine service environment rather than committing a token to scm.yml:

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

Example configuration:

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

For SSH mirrors, configure an SSH key for the Redmine application user and add github.com to that user's known_hosts. For HTTPS mirrors, repository-specific credentials can be entered in the Redmine repository form; configure Redmine's database encryption key before storing repository credentials.

Webhook registration requires a token with repository webhook write access and a public Redmine protocol and host configuration. Existing public GitHub repositories can be mirrored without a token when webhook registration is not required.

Update¶

1. Back up the database, config/scm.yml and the existing plugin directory.
2. Replace plugins/redmine_scm with the new release files. Keep the deployment-specific config/scm.yml under the Redmine config directory.
3. From the Redmine root, run:

bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production

1. Restart Redmine.
2. Test repository creation for every enabled local provider and test GitHub connectivity where applicable.

Uninstall¶

Before uninstalling, decide how existing plugin-managed repository registrations and filesystem repositories should be retained or removed. Rolling back the plugin migration removes the repositories.created_with_scm database column but does not remove repository directories.

From the Redmine root, roll back the plugin migration before deleting the plugin directory:

bundle exec rake redmine:plugins:migrate NAME=redmine_scm VERSION=0 RAILS_ENV=production

Restart Redmine after removing plugins/redmine_scm. Remove config/scm.yml only when it is no longer needed by this deployment, and remove repository data only through a deliberate, separately verified administrative process.