GitLab connector settings reference

Add a connector for your GitLab account or repository.

Before Harness uses this connector to sync with your Git repo, it confirms that the connector settings are valid. If the connection fails, Harness can't sync with your Git repo.

Overview settings

• Name: The unique name for this connector. Harness generates an Id (Entity Identifier) based on the Name. You can edit the Id during initial connector creation. Once you save the connector, the Id is locked.
• Description: Optional text string.
• Tags: Optional labels you can use for filtering. For details, go to the Tags reference.

Details settings

The Details settings specify which GitLab account or repository you want this connector to connect to, whether to connect over HTTP or SSH, and the URL to use.

URL Type

Select Account to connect an entire GitLab account. This option lets you use one connector to connect to all repositories in the specified GitLab account. Make sure you have at least one repo in the account; you need a repo to test the connection and save the connector.

Select Repository to connect to a single, specific repo in a GitLab account.

Connection Type

Select the protocol, HTTP or SSH, to use for cloning and authentication. The Connection Type determines the URL format required for the GitLab Account/Repository URL field. It also determines the Authentication method you must use in the Credentials settings.

GitLab Account/Repository URL

Enter the URL for the GitLab account or repository that you want to connect to. The required value is determined by the URL Type and Connection Type.

URL Type: Account

In the GitLab Account URL field, provide only the account-identifying portion of the GitLab URL, such as https://gitlab.com/YOUR_ACCOUNT_NAME/. Do not include a repo name. The URL format depends on the Connection Type:

• HTTP: https://gitlab.com/YOUR_ACCOUNT_NAME/ or https//gitlab.com
• SSH: git@gitlab.com:YOUR_ACCOUNT_NAME/

Test Repository

This field is only required if the URL Type is Account. Provide the name of a repo in your GitLab account that Harness can use to test the connector. Harness uses this repo to validate the connection only. When you use this connector in a pipeline, you'll specify a true code repo in your pipeline configuration or at runtime.

URL Type: Repository

In the GitLab Repository URL field, provide the complete URL to the GitLab repository that you want this connector to point to. The URL format depends on the Connection Type:

• HTTP: https://gitlab.com/YOUR_ACCOUNT_NAME/YOUR_REPO_NAME
• SSH: git@gitlab.com:YOUR_ACCOUNT_NAME/YOUR_REPO_NAME

Credentials settings

Provide authentication credentials for the connector.

Authentication

Authentication is required for all accounts and repos, including read-only repos. The Connection Type you chose in the Details settings determines the available Authentication methods:

• For HTTP connections, you can use OAuth, Username and Password, or Username and Token authentication.
• For SSH connections, you must use SSH Key authentication.

Username and Password

Username and Password authentication is not valid for GitLab accounts with two-factor authentication. Instead, use Username and Token, OAuth, or SSH Key authentication.

1. For Authentication, select Username and Password.
2. In the Username field, enter git. Do not enter any other value besides git.
3. In the Password field, provide your GitLab account password as a Harness encrypted text secret.

Username and Token

1. For Authentication, select Username and Token.
2. In the Username field, enter git. Do not enter any other value besides git.
3. In the Personal Access Token field, provide a GitLab personal access token as a Harness encrypted text secret.

Personal access token permissions

Make sure your personal access token has the following permissions: api, read_repository, and write_repository.

OAuth

note

Currently, OAuth for GitLab connectors is behind a feature flag. Contact Harness Support to enable the feature.

1. For Authentication, select OAuth.
2. Select Link to GitLab to open a new browser tab and authorize access to your GitLab account.

SSH Key

SSH connections require an SSH Key in PEM format. OpenSSH keys are not supported. In Harness, SSH Keys are stored as Harness SSH credential secrets. When creating an SSH credential secret for a code repo connector, the SSH credential's Username must be git.

For details on creating SSH keys and adding them to your GitLab account, go to the GitLab documentation about Using SSH keys to communicate with GitLab.

tip

If you use the keygen command to generate an SSH key, include arguments such as rsa and -m PEM to ensure your key is properly formatted and uses the RSA algorithm. For example, this command creates an SSHv2 key:

ssh-keygen -t rsa -m PEM

Make sure to follow the prompts to finish creating the key. For more information, go to the Linux ssh-keygen man page.

To sync with GitLab, you must generate an SSH key pair and add the SSH key to your GitLab account. For more information, go to the GitLab documentation on Generating a new SSH key pair.

Enable API access

This setting is only available for connection types and authentication methods where it is not enabled by default.

You must enable API access to use Git-based triggers, Git Sync, manage webhooks, or update Git statuses with this connector. If you are using the Harness Git Experience, this setting is required. API access requires personal access token authentication.

In the Personal Access Token field, provide a GitLab personal access token as a Harness encrypted text secret. If you selected Username and Token authentication, use the same personal access token secret for both Personal Access Token fields.

Personal access token permissions

Make sure your personal access token has the following permissions: api, read_repository, and write_repository.

If necessary, use the API URL field to override the default URL for API authentication. This is primarily for the Harness Self-Managed Enterprise Edition.

Connectivity Mode settings

Select whether you want Harness to connect directly to your GitLab account or repo, or if you want Harness to communicate with your GitLab account or repo through a delegate.

Delegates Setup

If you select Connect through a Harness Delegate, you can select Use any available Delegate or Only use Delegates with all of the following tags.

If you want to use specific delegates, you must identify those delegates. For more information, go to Select Delegates with Tags.

Kubernetes delegate with self-signed certificates

If your codebase connector allows API access and connects through a Harness Delegate that uses self-signed certificates, you must specify ADDITIONAL_CERTS_PATH in the delegate pod, as described in Configure a Kubernetes build farm to use self-signed certificates.