Connecting to a remote repository automatically

Edit online

By default, all projects that are created on the Automation Decision Services platform are not connected to a remote Git repository (remote repository). However, you can configure the platform to automatically create a remote repository and connect new projects to it.

Before you begin

You need to have the role for administering the Automation Decision Services platform to configure the automatic connection to a remote repository. For more information about the admin role, see Managing user permissions.

When you configure the automatic connections, the following things are possible:

When a user creates a project, it is connected to a remote repository automatically. This is applied for all users.
When the automatic connection fails, the project is still created but it is not connected to a remote repository.
When the automatic connection fails, you can still connect to another remote repository manually. For more information, see Connecting to a remote repository manually.

Restriction: You can configure one Git provider only. This Git provider is used for all users.

About this task

You can configure to automatically connect to a remote repository by calling a REST API method for Automation Decision Services.

To do so, you must use a valid Zen bearer token.

Procedure

Configure, display, delete, or update the automatic connection by sending a REST API HTTP call.

Configuring for the automatic connection

To configure for automatically connecting to a remote repository, use this REST API endpoint:

POST ads/rest-api/api/admin/git-providers

JSON body:

{
"name": "my-provider",
"uri": "https://my-server.com",
"type": "GITHUB",
"usePrivateFlag": true,
"apiCredentialsType": "USERNAME_PASSWORD",
"apiCredentials": "my-user:my-password",
"gitCredentialsType": "USERNAME_PASSWORD",
"gitCredentials": "my-user:my-password"
}

Table 1. Attributes
Attribute	Mandatory or Optional	Description
`name`	Mandatory	A unique name for your Git provider.
`uri`	Mandatory	The URL for your Git provider API. The current default paths for the supported Git providers: Gitea: `https://my-server.com/api/v1` GitHub: `https://my-server.com/api/v3` GitLab: `https://my-server.com/api/v4` Tip: You might need to use a different URL and path for specific cases; for example, for `https://github.com`, the URL for the provider API is `https://api.github.com`. The `https` protocol must be used. Certificates must be properly recognized by the Git service pods.
`type`	Mandatory	The type of your provider. You can choose one of them: `GITEA` `GITHUB` `GITLAB`
`apiCredentialsType`	Mandatory	The type of credentials to access the Git provider API. `USERNAME_PASSWORD` is compatible with Gitea or GitHub. `ACCESS_TOKEN` is compatible with Gitea, GitHub, or GitLab. You cannot use a clear password for GitHub, and it must be a personal access token instead.
`apiCredentials`	Mandatory	The value of the credentials. When you use username and password, they must be separated by a colon (`:`).
`gitCredentialsType`	Mandatory	The type of credentials to access the git repositories. You can use one of them: `USERNAME_PASSWORD` `ACCESS_TOKEN` `KEY` (SSH key)
`gitCredentials`	Mandatory	The value of the credentials. Restriction: You can use only RSA or OpenSSH format.
`remoteOrg`	Optional	The organization and namespace to create the repository into. When it's left empty, it uses the default organization of the user that is defined in the `apiCredentials` attribute.
`usePrivateFlag`	Optional	It is set to false by default. When it is set to true, the remote repository has private visibility. Note: If you set it to true, the user who is defined in the `gitCredentials` attribute must have access to the remote repository. Use the same user as the one defined in `apiCredentials`, or use organization privileges.

Displaying the automatic connection

To display the automatic connection, use this REST API endpoint:

GET  ads/rest-api/api/admin/git-providers

The credentials are not displayed for security reasons.

Disabling the automatic connection

To disable the automatic connection, use this REST API endpoint:

DELETE ads/rest-api/api/admin/git-providers/my-provider

where my-provider is the name of the provider to be deleted.

Updating the automatic connection

To update the automatic connection, use this REST API endpoint:

POST ads/rest-api/api/admin/git-providers/my-provider

where my-provider is the name of the provider to be updated.

JSON body is the same as the one that is described in Configuring for automatically connecting to a remote repository:

You must provide all attributes, except that you can omit the credentials. When you don't provide the credentials, they remain unchanged.

Restriction: You cannot update the credentials types: apiCredentialsType and gitCredentialsType.
When you provide the Git credentials, the corresponding secret value is updated. All Git repositories that are previously created with this provider are affected.