Repositories

Integrate source code repositories with Redmine projects, configure SCM binaries, and browse commits.

Redmine can integrate with source code repositories to display commits, browse code, and link commits to issues. Each project can have one or more repositories attached to it.

Supported SCMs

Git

The most commonly used SCM. Supports local and remote repositories. Configured via the git binary.

Subversion (SVN)

Supports both file:// and http(s):// repository URLs. Requires the svn binary.

Mercurial

Requires the hg binary. Configure the path in configuration.yml on Windows.

Bazaar

Requires the bzr binary. On Windows, .cmd and .bat wrappers do not work with CRuby — use the full path to the executable.

CVS

Legacy SCM support. Requires the cvs binary.

Filesystem

Browse a local filesystem directory as a read-only repository. No binary required.

Enabling SCM types

Only SCM types listed in Administration → Settings → Repositories → Enabled SCM are available when creating a repository in project settings.

The default enabled SCMs are:

config/settings.yml (default)

enabled_scm:
  - Subversion
  - Mercurial
  - Cvs
  - Bazaar
  - Git

Update this list in Administration → Settings → Repositories by checking or unchecking each SCM type.

SCM binary paths

Redmine calls SCM command-line binaries to fetch commits and display repository content. By default, it assumes each binary is available in PATH. You can override the command path for each SCM in config/configuration.yml:

config/configuration.yml

default:
  scm_subversion_command: svn                          # default: svn
  scm_mercurial_command:  /usr/local/bin/hg            # default: hg
  scm_git_command:        /usr/local/bin/git           # default: git
  scm_cvs_command:        cvs                          # default: cvs
  scm_bazaar_command:     bzr                          # default: bzr

On Windows with CRuby, .cmd and .bat files (e.g. hg.cmd, bzr.bat) do not work as SCM commands. Use the full path to the actual executable.

On Windows with JRuby 1.6.2, paths containing spaces do not work. Install SCM tools to a path with no spaces (e.g. C:\TortoiseHg\hg.exe instead of C:\Program Files\TortoiseHg\hg.exe).

Repository path validation

You can restrict which repository paths users are allowed to enter by configuring a regular expression per SCM. The expression is anchored (\A...\z) and case-sensitive:

config/configuration.yml

default:
  scm_subversion_path_regexp: file:///svnpath/[a-z0-9_]+
  scm_git_path_regexp: /gitpath/%project%(\.[a-z0-9_])?/

Use %project% in the pattern to match the project identifier.

You can also set a custom hint message shown on the repository form:

config/configuration.yml

default:
  scm_subversion_path_info: "SVN URL (e.g. file:///svnpath/foo)"

Adding a repository to a project

1. Open a project and go to Settings → Repositories.
2. Click Add a new repository.
3. Select the SCM type from the drop-down (only enabled SCMs appear).
4. Enter the repository URL or local path.
5. For repositories requiring authentication, enter the credentials. Credentials are stored encrypted in the database when database_cipher_key is configured in config/configuration.yml.
6. Click Create.

Fetching commits

Automatic fetch

When Autofetch changesets is enabled (Administration → Settings → Repositories), Redmine fetches new commits from the repository each time a user views the repository browser. This is the default behavior (autofetch_changesets: 1).

Manual fetch

To fetch commits on a schedule without relying on browser visits, call the repository fetch URL with the API key:

curl "https://redmine.example.com/sys/fetch_changesets?key=your_sys_api_key"

Enable the system API and set the key at Administration → Settings → Repositories:

Setting	Description
sys_api_enabled	Enable the /sys/ API endpoint for repository management.
sys_api_key	Secret key required in the key parameter of sys API calls.

Webhook-based fetch (Git)

For Git repositories hosted on platforms that support webhooks, configure the platform to call the Redmine fetch URL on push events:

POST https://redmine.example.com/sys/fetch_changesets?key=your_sys_api_key

Linking commits to issues

Commits that mention an issue number are linked to that issue automatically. The keywords that trigger a reference are set in Administration → Settings → Repositories:

Setting	Default	Description
commit_ref_keywords	refs,references,IssueID	Keywords that create a reference link from the commit to the issue.
commit_update_keywords	(empty)	Rules that update issue status or other fields when a keyword appears in a commit message.
commit_cross_project_ref	0	Allow commits to reference issues in other projects using the project-identifier#123 format.

Commit update keywords

Commit update keyword rules map a keyword (e.g. fixes, closes) to an issue status change and optional done ratio update. Example: a commit message of fixes #123 with a rule for fixes can automatically close issue #123.

Rules are configured at Administration → Settings → Repositories → Commit update keywords.

SCM errors log

SCM command errors (stderr output) are written to the Redmine log directory by default. To redirect them to a separate file, set scm_stderr_log_file in config/configuration.yml:

config/configuration.yml

default:
  scm_stderr_log_file: /var/log/redmine_scm_stderr.log

Repository browser

The repository browser allows users to:

• Browse the directory tree at any revision.
• View file contents with syntax highlighting (powered by Rouge).
• Compare file revisions side by side.
• View the commit log for any file or directory.
• View diff output for each commit.

Access is controlled by the Browse repository permission on each role.

Setting	Default	Description
file_max_size_displayed	512 (KB)	Maximum file size that the inline file viewer will display.
diff_max_lines_displayed	1500	Maximum number of diff lines shown in the browser.