GitSwarm-EE 2017.1-1 Documentation

Configuration

Help / Workflow / Helix Mirroring / Configuration

Configuration

Before you can use Helix Mirroring, GitSwarm EE needs some configuration that describes where the Git Fusion service(s) exist.

For Helix Mirroring, GitSwarm EE needs to be configured to connect to one or more Git Fusion servers. GitSwarm EE always connects to a Git Fusion server as a specific user, gitswarm if you don't specify otherwise. The "gitswarm" user must exist in the Helix Versioning Engine as a standard user account (not an operator or service user). The "gitswarm" user does not need any special protections in the Helix Versioning Engine, but does require read/write access to the //.git-fusion depot.

Global Configuration

GitSwarm EE supports a special server entry called global, which contains defaults for usernames, passwords, git configuration parameters, and convention-based repository settings.

For package installations

This configuration should appear in /etc/gitswarm/gitswarm.rb:

gitswarm['git-fusion']['global']['user']      = 'global-user'
gitswarm['git-fusion']['global']['password']  = '<password for "global-user" user>'
gitswarm['git-fusion']['local']['url']        = 'http://gitswarm@gitfusion.host/'
gitswarm['git-fusion']['local']['password']   = '<password for "gitswarm" user>'
gitswarm['git-fusion']['development']['url']  = 'http://dev-gitfusion.host/'
gitswarm['git-fusion']['production']['url']   = 'http://prod-gitfusion.host/'

In the above example, the user global-user is used to log in to the development and production Git Fusion servers. The user for the local Git Fusion server remains as gitswarm.

Note: A global setting for url is ignored if present; each Git Fusion configuration should use a distinct url.

Note: The following priority is given to user/password lookups:

Entry-specific user/password keys

User/password specified on the Git Fusion server url

Global user/password

Default (gitswarm for user, '' for password)

For source installations

This configuration should appear in gitlab.yml:

git-fusion:
  global:
    user: global-user
    password: <password for "global-user" user>
  local:
    url: http://gitswarm@gitfusion.host/
    password: <password for "gitswarm" user
  development:
    url: http://dev-gitfusion.host/
  production:
    url: http://prod-gitfusion.host/

In the above example, the user global-user is used to log in to the development and production Git Fusion servers. The user for the local Git Fusion server remains as gitswarm.

Note: A global setting for url is ignored if present; each Git Fusion configuration should use a distinct url.

Note: The following priority is given to user/password lookups:

Entry-specific user/password keys

User/password specified on the Git Fusion server url

Global user/password

Default (gitswarm for user, '' for password)

Using an HTTP(S) connection

For package installations

Edit the following configuration in /etc/gitswarm/gitswarm.rb:

After the gitswarm['git-fusion']['enabled'] section:
```
gitswarm['git-fusion']['enabled']              = true
gitswarm['git-fusion']['my_entry']['url']      = 'http://gitswarm@gitfusion.host/'
gitswarm['git-fusion']['my_entry']['password'] = '<password for "gitswarm" user>'
```
Note: The "gitswarm" user needs to exist in the Helix Versioning Engine that the Git Fusion service uses, and must have permission to access the repositories you wish to import from.

Note: my_entry is an example key that is used to configure the connection to a particular Git Fusion server. Similarly, you can include configurations to other Git Fusion servers under other uniquely-named keys.
```
gitswarm['git-fusion']['local']['url']      = 'http://gitswarm@gitfusion.host/'
gitswarm['git-fusion']['local']['password'] = '<password for "gitswarm" user>'
gitswarm['git-fusion']['other']['url']      = 'http://other-user@other-gitfusion.host/'
gitswarm['git-fusion']['other']['password'] = '<password for "other-user" user>'
```
Note: While we do not recommend using self-signed SSL certificates (and these should never be used in production), if you are using self-signed certificates for HTTPS connections in a test environment, you need to specify:
```
gitswarm['git-fusion']['my_entry']['git_config_params'] = 'http.sslVerify=false'
```
Note: the key my_entry can be replaced with a unique value of your choosing.
Make the configuration change active:
```
sudo gitswarm-ctl reconfigure
```

For source installations

Edit the following configuration in gitlab.yml:
```
git-fusion:
  enabled: true
  my_entry:
    url: http://gitswarm@gitfusion.host/
    password: <password for "gitswarm" user>
```
Note: The "gitswarm" user needs to exist in the Helix Versioning Engine that the Git Fusion service uses, and must have permission to access the repositories you wish to import from.

Note: my_entry is an example key that is used to configure the connection to a particular Git Fusion server. Similarly, you can include configurations to other Git Fusion servers under other uniquely-named keys.
```
git-fusion:
  local:
    url: http://gitswarm@gitfusion.host/
    password: <password for "gitswarm" user>
  other:
    url: http://other-user@other-gitfusion.host/
    password: <password for "other-user" user>
```
Note: While we do not recommend using self-signed SSL certificates (and these should never be used in production), if you are using self-signed certificates for HTTPS connections in a test environment, you need to specify:
```
git-fusion:
  my_entry:
    git_config_params: http.sslVerify=false
```
Note: the key my_entry can be replaced with a unique value of your choosing.
Make the configuration change active:
```
sudo service gitlab restart
```

Using an SSH connection

For package installations

Add the following configuration to /etc/gitswarm/gitswarm.rb:

gitswarm['git-fusion']['enabled']               = true
gitswarm['git-fusion']['my_entry']['url']       = 'git@gitfusion.host'
gitswarm['git-fusion']['my_entry']['password']  = '<password for "gitswarm" user>'

Make this configuration change active:
```
sudo gitswarm-ctl reconfigure
```
Note: reconfigure also ensures that the "gitswarm" user has a public SSH key.

To permit GitSwarm EE to connect to Git Fusion via SSH, follow these steps:

Get a copy of the git user's public SSH key from the GitSwarm EE host machine.
```
sudo cat ~git/.ssh/id_rsa.pub
```
Note: It is possible to modify the username of the system user that GitSwarm-Shell uses. If you have modified the system username, replace git in the command above with the configured username.
Install the git user's public SSH key in the Git Fusion service.

This process involves interacting with the Helix Versioning Engine that the Git Fusion service connects to. The steps are described in the Git Fusion guide, in the section Authenticating Git Users using SSH.

For source installations

Add the following configuration to gitlab.yml:

git-fusion:
  enabled: true
  my_entry:
    url: git@gitfusion.host
    password: <password for "gitswarm" user>

Ensure that the "git" user has a public SSH key.
```
sudo -u git ssh-keygen
```
Make this configuration change active:
```
sudo service gitlab restart
```

To permit GitSwarm EE to connect to Git Fusion via SSH, follow these steps:

Get a copy of the git user's public SSH key from the GitSwarm EE host machine.
```
sudo cat ~git/.ssh/id_rsa.pub
```
Note: It is possible to modify the username of the system user that GitSwarm-Shell uses. If you have modified the system username, replace git in the command above with the configured username.
Install the git user's public SSH key in the Git Fusion service.

This process involves interacting with the Helix Versioning Engine that the Git Fusion service connects to. The steps are described in the Git Fusion guide, in the section Authenticating Git Users using SSH.

Helix Mirroring Configuration

In order for GitSwarm EE to automatically create new Git Fusion repositories when adding projects, GitSwarm EE needs to connect to the Helix Versioning Engine (P4D) directly. GitSwarm EE also needs to be configured with a path where it can place the repository files.

At a minimum, GitSwarm EE needs to be configured with a user id and password for the connection. When using HTTP(S), this information should already be present. When using SSH, you may need to add the settings:

For package installations:

Set the following in /etc/gitswarm/gitswarm.rb

gitswarm['git-fusion']['enabled']              = true
gitswarm['git-fusion']['my_entry']['url']      = 'git@gitfusion.host'
gitswarm['git-fusion']['my_entry']['user']     = '<perforce-user-id>'
gitswarm['git-fusion']['my_entry']['password'] = '<password for "gitswarm" user>'

For source installations:

git-fusion:
  enabled: true
  my_entry:
    url: git@gitfusion.host
    user: <perforce-user-id>
    password: <password for "gitswarm" user>

Note: If no port is specified under the perforce key, GitSwarm EE connects to the given Git Fusion server and uses the same port as Git Fusion (the my_entry Git Fusion server in the above example).

If the auto-detected Perforce Port is incorrect, you may optionally specify the appropriate value manually by setting:

For package installations:

gitswarm['git-fusion']['my_entry']['perforce']['port']  = 'ssl:my-fusion:1666'

For source installations:

git-fusion:
  my_entry:
    perforce:
      port: ssl:my-fusion:1666

Note: GitSwarm EE uses the following priority for determining user/password to connect to Perforce:

Entry-specific user/password keys

User/password specified on the Git Fusion server url

Global user/password

Default (gitswarm for user, '' for password)

Note: The user (e.g. gitswarm) needs to exist in the Helix Versioning Engine that the Git Fusion service uses, and must have permission to access the repositories you wish to import from.

Note: The my_entry key is used to assign config values to a particular Git Fusion server. You can include more configured servers under other keys.

Convention-based mirroring configuration

GitSwarm EE generates a Git Fusion configuration and unique depot path for each new project that has Helix Mirroring enabled. It constructs these by substituting the GitSwarm EE project's namespace and project path into a template that is specified in the configuration.

For package installations:

gitswarm['git-fusion']['global']['auto_create']['path_template']      = '//gitswarm/projects/{namespace}/{project-path}'
gitswarm['git-fusion']['global']['auto_create']['repo_name_template'] = 'gitswarm-{namespace}-{project-path}'

For source installations:

git-fusion:
  global:
    auto_create:
      path_template: //gitswarm/projects/{namespace}/{project-path}
      repo_name_template: gitswarm-{namespace}-{project-path}

Note: {namespace} and {project-path} are substituted for the GitSwarm EE project's namespace and project path (name) when the project is created.

Note: The depot specified in the path_template ('gitswarm' in the above example) must exist prior to attempting to use the convention-based repository feature. GitSwarm EE does not create this depot for you.

Sample Configuration

The following is a sample configuration for GitSwarm EE, including Helix Versioning Engine integration, and convention-based mirroring settings

For package installations:

gitswarm['git-fusion']['enabled']                                       = true
gitswarm['git-fusion']['my_entry']['url']                               = 'git@gitfusion.host'
gitswarm['git-fusion']['my_entry']['user']                              = '<perforce-user-id>'
gitswarm['git-fusion']['my_entry']['password']                          = '<password for "gitswarm" user>'
gitswarm['git-fusion']['my_entry']['perforce']['port']                  = 'ssl:my-fusion:1666'
gitswarm['git-fusion']['my_entry']['auto_create']['path_template']      = '//gitswarm/projects/{namespace}/{project-path}'
gitswarm['git-fusion']['my_entry']['auto_create']['repo_name_template'] = 'gitswarm-{namespace}-{project-path}'

For source installations:

git-fusion:
  enabled: true
  my_entry:
    url: git@gitfusion.host
    user: <perforce-user-id>
    password: <password for "gitswarm" user>
    perforce:
      port: ssl:my-fusion:1666
    auto_create:
      path_template: //gitswarm/projects/{namespace}/{project-path}
      repo_name_template: gitswarm-{namespace}-{project-path}