Document toolboxDocument toolbox

Configuring MettleCI Workbench to communicate with Git over HTTPS

Owned by Drew Nuttall-Smith
Last updated: Feb 17, 2023 by John McKeever
4 min read

Note

This page describes the functionality of MettleCI Workbench version 1.0-1280 and later.
For older versions of Workbench, see this page: https://datamigrators.atlassian.net/wiki/spaces/MCIDOC/pages/1112375301

Data Migrators recommend using the SSH protocol for authentication between MettleCI Workbench and your remote Git repositories as it is easier to manage access in a uniform manner across multiple remote Git repository hosts (Github, Bitbucket, Gitlab, etc). SSH keys also tend to be more secure than username/password credentials.

Config.yml Changes

Warning

Upgrading MettleCI Workbench from a version prior to 1.0-1280 will result in a breaking change for customers using Git over HTTPS.
The global HTTPS credentials defined using the yaml keys httpsUsername and httpsPassword under the gitAuthentication section of the config.yml file are no longer used in MettleCI Workbench version 1.0-1280 onwards. The continued presence of those values in that file will not cause any adverse behaviour, but those values will be ignored, and would be better removed from the file to avoid confusion.

In the event that you need to use Git over HTTPS rather than SSH you can configure MettleCI Workbench to store a set of username/password credentials for each user which will be used for all Git HTTPS requests.

These are configured in the config.yml file as shown below:

... gitAuthentication: sshKey: "/opt/dm/mci/workbench.key" # Location of our private SSH key httpsEnabled: true # Set true to use HTTPS httpsProvider: "SunJSSE" # httpsCredentialsStore: # Details of the SSL certificate file type: "PKCS12" path: "/opt/dm/mci/.secrets/git-credentials.p12" password: ${file:UTF-8:/opt/dm/mci/.secrets/git-credentials-keystore-password} ...

The comments in the example above are just for clarity. You should not have any comments or trailing whitespace after the entries in your config.yml.

This password will be stored in a file (.secrets/git-credentials-keystore-password) referenced in the config.yml file, as shown above.

The git credentials will be stored in a keystore (.secrets/git-credentials.p12) that requires the keystore password and will be created when the config option httpsEnabled: true has been added to the config.yml

Generating the Git Credentials KeyStore

The Workbench Setup Wizard will automatically generate the .secrets/git-credentials-keystore-password file for you with MettleCI Workbench version 1.0-1327 and later

  1. Make sure the MettleCI Workbench Service is stopped

    $> service dm-mettleci-workbench stop

  2. Edit the config.yml file and add or set the httpsEnabled entry under the sshKey entry. Make sure it is set to false for the time being.

    gitAuthentication: sshKey: "/opt/dm/mci/workbench.key" httpsEnabled: false

  3. In order to create the password file make sure to login as the mciworkb user.

  4. Edit the file with your preferred editor and enter a new password

  5. Edit the config.yml file and add or set the httpsEnabled entry to true under the sshKey entry.

  6. MettleCI Workbench will need to be restarted after saving changes to config.yml.

  7. Check that the keystore has been created by MettleCI Workbench

User Profile Git Configuration

When HTTPS is enabled, each user can add their git credentials on the Profile page which they can access from the menu in the top right corner of Workbench:

You can then enter Git HTTPS or SSH repository URLS in the project registration page. The ssh or https credentials will be used depending on the configured Git protocol, any username shown in the URL will be ignored and overridden by the settings included in config.yml:

 

© 2015-2024 Data Migrators Pty Ltd.