> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-lab-connector-settings-reference.md).

# 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 <a href="#overview-settings" id="overview-settings"></a>

* **Name:** The unique name for this connector. Harness generates an **Id** ([Entity Identifier](/harness-platform/use-harness-platform/references/entity-identifier-reference.md)) 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](/harness-platform/use-harness-platform/tags/overview.md#create-tags-for-pipelines).

### Details settings <a href="#details-settings" id="details-settings"></a>

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 <a href="#url-type" id="url-type"></a>

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 <a href="#connection-type" id="connection-type"></a>

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](#credentials-settings).

#### GitLab Account/Repository URL <a href="#gitlab-accountrepository-url" id="gitlab-accountrepository-url"></a>

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**.

{% tabs %}
{% tab title="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 <a href="#test-repository" id="test-repository"></a>

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.
{% endtab %}

{% tab title="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`
  {% endtab %}
  {% endtabs %}

### Credentials settings <a href="#credentials-settings" id="credentials-settings"></a>

Provide authentication credentials for the connector.

#### Authentication <a href="#authentication" id="authentication"></a>

Authentication is required for all accounts and repos, including read-only repos. The **Connection Type** you chose in the [Details settings](#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.

{% tabs %}
{% tab title="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](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).
   {% endtab %}

{% tab title="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](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) as a [Harness encrypted text secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).

{% hint style="info" %}
**PERSONAL ACCESS TOKEN PERMISSIONS**

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

<img src="/files/HhYHp5l5KjsZ5GgnffNS" alt="" data-size="original">
{% endhint %}
{% endtab %}

{% tab title="OAuth" %}

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

{% tab title="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](/harness-platform/use-harness-platform/secrets/add-use-ssh-secrets.md). When creating an SSH credential secret for a code repo connector, the SSH credential's **Username** must be `git`. Always save the ssh key as a file secret.

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](https://docs.gitlab.com/ee/user/ssh.html).

{% hint style="info" %}
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](https://linux.die.net/man/1/ssh-keygen).

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 [Using SSH keys to communicate with GitLab](https://docs.gitlab.com/ee/user/ssh.html).
{% endhint %}
{% endtab %}
{% endtabs %}

#### Enable API access <a href="#enable-api-access" id="enable-api-access"></a>

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](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) as a [Harness encrypted text secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md). If you selected **Username and Token** authentication, use the same personal access token secret for both **Personal Access Token** fields.

{% hint style="info" %}
**PERSONAL ACCESS TOKEN PERMISSIONS**

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

<img src="/files/HhYHp5l5KjsZ5GgnffNS" alt="" data-size="original">
{% endhint %}

**API URL**

If you have a GitLab self-managed plan and your base URL format is something like `https://myloadbalancer/gitlab`, then you must provide your GitLab base URL in the **API URL** field. Harness uses this URL for API authentication.

Don't specify an API URL if you use GitLab SaaS or your GitLab self-managed plan's base URL is formatted like `https://mygitlab.internal`.

### Connectivity Mode settings <a href="#connectivity-mode-settings" id="connectivity-mode-settings"></a>

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. If you plan to use this connector with [Harness Cloud build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md), you must select **Connect through Harness Platform**.

{% hint style="info" %}
For private network connectivity options with Harness Cloud, see [Private network connectivity options](/harness-platform/use-harness-platform/references/private-network-connectivity/private-network-connectivity.md).
{% endhint %}

#### Delegates Setup <a href="#delegates-setup" id="delegates-setup"></a>

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 [Use delegate selectors](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md).

#### Kubernetes delegate with self-signed certificates <a href="#kubernetes-delegate-with-self-signed-certificates" id="kubernetes-delegate-with-self-signed-certificates"></a>

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](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates.md#enable-self-signed-certificates).