Configuration file format¶

• Configuration file format
  • Global configuration
    • auto_create
    • only_creator
    • force_repository
    • deny_delete
    • max_repos
    • allow_add_local
    • allow_pickup
  • Scripts
  • Common configuration
    • path
    • options
    • url
    • append
  • Subversion configuration
    • svnadmin
  • Git configuration
    • git
    • update_server_info
    • git_ext
  • Mercurial configuration
    • hg
  • Bazaar configuration
    • bzr
    • init
    • log_encoding
  • Github configuration
    • options
    • api
      • token
      • username/password
      • register_hook

The configuration of the plugin is stored in the #{RAILS_ROOT}/config/scm.yml file. This file is loaded once; that is, you need to restart Redmine/ChiliProject to apply any changes you have made.

Sample file:

production:
  deny_delete: false
  auto_create: false
  force_repository: false
  pre_create: /usr/local/bin/pre-create.sh
  post_create: /usr/local/bin/post-create.sh
  pre_delete: /usr/local/bin/pre-delete.sh
  post_delete: /usr/local/bin/post-delete.sh
  max_repos: 0
  only_creator: false
  allow_add_local: false
  allow_pickup: false
  svn:
    path: /var/lib/svn
    svnadmin: /usr/bin/svnadmin
    url: svn
  git:
    path: /var/lib/git
    git: /usr/bin/git
    options: --bare
    url: http://git.myhost.com
    update_server_info: true
    git_ext: true
    append: trunk
  mercurial:
    path: /var/lib/mercurial
    hg: /usr/bin/hg
  bazaar:
    path: /var/lib/bazaar
    bzr: /usr/bin/bzr
    init: init-repository
    log_encoding: UTF-8
  github:
    path: /var/lib/github

The configuration of the plugin must be specified under the production section or under the development section depending on what environment settings are you using (usually it's production).

Check also common configuration scenarios...

Global configuration¶

Global options apply for all SCM 's.

auto_create¶

Possible values are:

• false
  Normal operation. A user can create a repository using the Repository tab in project settings.

• true
  If SCM type is specified/configured (currently it can be either "Subversion", "Git", "Mercurial" or "Bazaar") on the moment of the project registration a repository is created automatically. The project registration form contains an element for choosing the SCM type.

• force
  A repository is created automatically on project registration. If only one SCM is enabled a repository for this SCM is created. If more than one SCM is enabled the project registration form contains a required element for choosing the SCM type.

only_creator¶

Specifies if Redmine should allow only repositories created with SCM Creator. This option is for multiple repositories i.e. for Redmine 1.4.x and above.

Till 1.4.x to achieve the same effect you just needed to set auto_create and deny_delete to true.

force_repository¶

Specifies if the Repository module should be enabled on project creation. If set to true the Repository module checkbox also becomes disabled to prevent unchecking.

This option overwrites default enabled modules from administration settings.

deny_delete¶

The deny_delete option can be equal either to true or to false. If the deny_delete option is equal to true the plugin won't allow deleting repositories created with the plugin.

This does not effect project deletion.

max_repos¶

The maximum number of repositories SCM Creator can create for a project. Zero (default value) means this number is not limited. This option works only for Redmine 1.4.x and above (and is not needed for ChiliProject and Redmine 1.3.x and below).

This option does not effect (and does not take into account) added (not created) repositories.

allow_add_local¶

Specifies if local repositories can be added. By default it's false what does not allow adding local repositories.

allow_pickup¶

Specifies if, when new project is created, SCM Creator should automatically pick up existing repository with the same name as the identifier of new project. Defaults to false.

The default value changes the previous behavior of SCM Creator. To restore set it to true explicitly.

Scripts¶

Since version 0.3.0 the plugin supports custom scripts which can be executed before repository creation pre_create, after repository creation post_create, before repository removal pre_delete or after repository removal post_delete:

production:
  pre_create: /usr/local/bin/pre-create.sh
  post_create: /usr/local/bin/post-create.sh
  pre_delete: /usr/local/bin/pre-delete.sh
  post_delete: /usr/local/bin/post-delete.sh

The pre_create, post_create, pre_delete and post_delete options are global.

Check this page for more information how scripts can be used.

Common configuration¶

The following options are common for all SCMs:

path¶

This option specifies the path to the SCM root directory (the directory where repositories are stored). For Subversion this should be /var/lib/svn, for Git this should be /var/lib/git, for Mercurial this should be /var/lib/mercurial, for Bazaar this should be /var/lib/bazaar and for Github this should be /var/lib/github.

options¶

If you need to specify command line options for svnadmin, git, hg or bzr use options. This option is used by default for Git (adds --bare):

    ...
    git: /usr/bin/git
    options: --bare
    ...

You can also add more than one option:

    ...
    git: /usr/bin/git
    options:
      - --bare
      - --shared=group
    ...

This will produce the following command:

$ /usr/bin/git init --bare --shared=group /var/lib/git/<repo>

For Github options are used differently (as parameters for Github API), see below.

url¶

The url option can be used to specify an external URL for a repository (e.g. http://subversion.andriylesyuk.com/redmine-svn). Currently external URL is shown only in the Repository form when the repository exists.

The value of the url option can be absolute or relative. Absolute values should start with:

• file://, http://, https://, svn:// or svn+*:// (e.g. svn+ssh://) for Subversion;
• http://, https://, git:// or ssh:// for Git;
• http://, https:// or ssh:// for Mercurial;
• sftp:// or bzr+*:// (e.g. bzr+ssh://) for Bazaar.

If an absolute URL is specified the external URL is obtained by appending the repository name (e.g. if url is http://subversion.andriylesyuk.com the external URL will be http://subversion.andriylesyuk.com/<repo>). Otherwise the external URL is built by concatenating Redmine/ChiliProject host, url and a repository name (e.g. if url is svn the external URL will be <Redmine host>/svn/<repo>).

Github SCM does not use this option.

append¶

The append option specifies the trailing directory for the repository URL. That is the value of the append option is automatically added to the end of the repository URL. For example, if SVN path is /var/lib/svn, the repository name is project and the append is trunk the final repository URL will be /var/lib/svn/project/trunk.

Github SCM does not use this option.

Subversion configuration¶

Subversion configuration exists if there is the svn section in the #{RAILS_ROOT}/config/scm.yml file.

production:
  svn:
    path: /var/lib/svn
    svnadmin: /usr/bin/svnadmin

The path and svnadmin options are required.

The following options are specific to Subversion:

svnadmin¶

Specifies the path to the svnadmin tool. The path usually is /usr/bin/svnadmin. To be sure you can determine the path to the tool by executing command:

$ which svnadmin
/usr/bin/svnadmin

Git configuration¶

Git configuration exists if there is the git section in the #{RAILS_ROOT}/config/scm.yml file.

production:
  git:
    path: /var/lib/git
    git: /usr/bin/git

The path option is required.

The following options are specific to Git:

git¶

Specifies the path to the git tool. The path usually is /usr/bin/git. To be sure you can determine the path to the tool by executing command:

$ which git
/usr/bin/git

update_server_info¶

If you plan to allow using Git over HTTP (what is needed for a better Redmine/Git integration) you need to set the update_server_info option to true.

git_ext¶

By default created repository directories will contain .git extension. To change this set the git_ext option to false.

Mercurial configuration¶

Mercurial configuration exists if there is the mercurial section in the #{RAILS_ROOT}/config/scm.yml file.

production:
  mercurial:
    path: /var/lib/mercurial
    hg: /usr/bin/hg

The path option is required.

The following options are specific to Mercurial:

hg¶

Specifies the path to the hg tool. The path usually is /usr/bin/hg. To be sure you can determine the path to the tool by executing command:

$ which hg
/usr/bin/hg

Bazaar configuration¶

Bazaar configuration exists if there is the bazaar section in the #{RAILS_ROOT}/config/scm.yml file.

production:
  bazaar:
    path: /var/lib/bazaar
    bzr: /usr/bin/bzr

The path option is required.

The following options are specific to Bazaar:

bzr¶

Specifies the path to the bzr tool. The path usually is /usr/bin/bzr. To be sure you can determine the path to the tool by executing command:

$ which bzr
/usr/bin/bzr

init¶

Unlike other SCMs Bazaar supports several commands for creating new repositories. For example, just init, init-repository etc.

The init option specifies which command to use. If no command is specified Bazaar uses the init-repository command:

$ /usr/bin/bzr init-repository <path>

log_encoding¶

Unlike other SCMs (again) the Bazaar repository form in Redmine requires the additional field "Commit messages encoding". As far as the SCM Creator can be used to create repositories automatically on project creation the additiona option log_encoding has been added. If not specified Bazaar will use UTF-8.

Github configuration¶

Github configuration exists if there is the github section in the #{RAILS_ROOT}/config/scm.yml file.

production:
  github:
    path: /var/lib/github
    options:
      has_wiki: false
    api:
      username: login
      password: password
      token: 36857b12efbccc64ce725ea8674fab6ecbd05c03
      register_hook: true

The path option is required. This option enables adding remote Github repositories.

The api subsection and either username/password or token options are required, if you want to use SCM Creator for creating remote Github repositories.

The following options are specific to Github:

options¶

The value of Github options is used as input parameters for the repository creation request to Github API.

Thus, at the moment (for API v3) among the supported parameters are:

• private -- indicates, if the repository is to be private.
• has_issues -- indicates, if Github issue tracking should be enabled for the repository.
• has_wiki -- indicates, if Github Wiki should be enabled for the repository.
• has_downloads -- indicates, if downloads should be enabled for repository files.
• team_id -- can be used to specify the id of the Github team.
• auto_init -- adds README to the just created repository.

See also: https://developer.github.com/v3/repos/#create

api¶

The api subsection should be specified, if you plan to use SCM Creator for creating new Github repositories. Without this section you will only be able to add existing repositories (no "Create new repository" button will be available).

The following options can be specified in the api subsection:

token¶

To be able to use Github API (i.e., to be able to create new repositories) you need to specify either the API token or the authentication credentials. The api token should be preferred and is recommended.

The API token should be specified in the api -> token option.

The API token can be created in your Github user profile as described here .

username/password¶

Alternatively, to use Github API you can specify your login and password in username and password options. But it's not recemmended!

register_hook¶

This option specifies, if the Redmine service hook can/should be registered for Github repositories. This service allows Redmine to be notified about new commits to the Github repository and normally is useful only when the "Fetch commits automatically" option (in Administration -> Settings -> Repositories) is unchecked.

Possible values for this option are:

• forbid
  Do not allow registering the Redmine service hook.

• false
  Never register the Redmine service hook by default.

• true
  Enable the "Register hook for fetching commits" option in the form by default, but not for already existing repositories.

• force
  Always register the Redmine service hook, when it's possible. This value can be especially usuful, when the auto_create option is enabled.