Connecting an ADS project to a GitHub repository

This note explains in details how to connect an ADS project to a GitHub repository. You have created a project using Decision Designer and you want to synchronize its content with a GitHub repository. The first step is to create this GitHub repository. Then you can connect to it using two modes, either HTTPS either SSH, both are described in this note.
It has been tested on ADS 21.0.2. 

Creating a GitHub repository.

You sign into your GitHub account. If you don’t have a GitHub account you can create one, look at the GitHub documentation to proceed. You create an empty repository on GitHub . You give it a unique repository name and a short description. You can choose to make it public or private. Make sure you don’t add any files to the new repository. It has to be empty to be able to be connected to an ADS project. The following image shows how to create an empty private repository named testRepository.

Next you need to get the settings required by ADS to connect to this repository: an URI and credentials.

Using HTTPS mode.

The first approach is to get the URL of this repository in HTTPS  mode. The SSH mode will be explained in a second part.

In HTTPS mode, you provide a user and a personal access token generated by GitHub to be used as a password. First, copy the HTTPS URL to be used later. The HTTPS URL in this example is https://github.com/teamauthoring/testRepository.git

You need to generate a personal access token to be able to connect to your GitHub repository. In GitHub, open the Settings panel of your account.

On the left select Developer settings and then the Personal access tokens option.

Click on Generate new token. Enter a reminder note, choose the expiration date and select the scopes for this personal access token. In this example, the repo scope is selected to provide the full control of repositories.

Click on Generate token at the end of the page. Copy the generated access token before closing this page, because GitHub will no more show it.

Next time, you open the Personal access tokens in GitHub, you will no longer see its value and you may delete it if necessary.

Now you can connect your decision project to this Git repository. In Decision Designer, click on the Connect icon in the top right corner. Set the repository URI and choose the Username & password credentials type. Enter your user name and the personal access token generated in GitHub as the password.

Click on Connect:  you successfully connected your project. It means that all the changes you share on your project are saved in your GitHub repository. Note that the API key credential type is not supported in GitHub.

You can at any time create or update the credentials you provided for this Git repository by selecting the Create or update credentials for the project button.

Using SSH mode.

Second approach is to use SSH mode. In GitHub, after creating the empty repository, select SSH. In this example, the SSH URL is git@github.com:teamauthoring/testRepository.git. Copy it to be used later.

Then you have to generate a SSH key using a terminal command. A SSH key has two parts: a public one that you put in GitHub and a private one that you put in ADS.
Open a terminal, navigate in a directory where the files of the two parts of the key will be generated, enter the following command

     ssh-keygen -t rsa -b 4096 -C “your_email@example.com” -m PEM -f <key_name>

where you put your email address and the name of the key. When asked make sure you give no passphrase. For more information about the parameters, look at the GitHub documentation about SSH.

For example:

$ ssh-keygen -t rsa -b 4096 -C “mymail@example.com” -m PEM -f testKey

Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in testKey.
Your public key has been saved in testKey.pub.

Two files are generated in your directory: testKey contains the private part of the key that you will put into Decision Designer and testKey.pub contains the public part of the key that you will put into GitHub.

First, you enter the public part of the key. In GitHub, open the Settings panel of your account:

On the left select SSH and GPG keys in the Account settings.

Click on New SSH key. Enter a key title and paste the content of the testKey.pub file in the Key part.

Then click on Add SSH key. This key is added to your GitHub account, you can delete it if you don’t use it anymore.

Now you can connect the repository in Decision Designer using the private part of the key.

In Decision Designer, click on the Connect icon in the top right corner. Set the repository URI and choose SSH key in the credentials type. Paste the full contents of the testKey file in the SSH key part.

Click on Connect:  you successfully connected your project. It means that all the changes you share on your project are saved in your GitHub repository. Note that the API key credential type is not supported in GitHub.

You can at any time create or update the credentials you provided for this Git repository by selecting the Create or update credentials for the project button.

Thanks to my colleague @Jerome Joubert for his help on this content.