> 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/add-a-gitlab-connector.md).

# Add a GitLab connector

Add a GitLab connector so Harness pipelines can pull code and other files from your GitLab.com or self-managed GitLab repositories.

GitLab is a Git repository management platform offered as a cloud-hosted service (GitLab.com) and as a self-managed instance. Besides repository hosting, GitLab provides built-in CI/CD pipelines, issue tracking, and container/package registries. Harness supports connecting to both GitLab.com (Cloud) and self-managed GitLab instances.

You connect Harness to GitLab using a Harness GitLab connector. This connector allows you to pull code and other files, such as Helm charts, Kubernetes manifests, and Terraform scripts, from your GitLab repositories for use in Harness pipelines.

Go to [Overview](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/code-repositories-connectors-overview.md) for information about all code repos connectors, such as scopes, permissions and connectivity modes.

## What you will learn from this topic

* How to [add a GitLab connector](#add-a-gitlab-connector) to a Harness project so pipelines can pull code from GitLab.

***

## Before you begin

Before you create a GitLab connector, ensure you have:

* A GitLab account or self-managed GitLab instance, with at least one repository.
* A personal access token, or SSH key, with permission to read the repositories you want to connect to.
* Permission to create connectors in Harness.

***

## Add a GitLab connector

You can add a GitLab connector at the project, org, or account scope. This procedure covers the project scope, and the process is the same for org and account.

You can also add a GitLab connector directly when configuring a GitLab codebase or artifact source in a pipeline or service.

Follow the interactive guide below for a step-by-step walkthrough:

{% embed url="<https://app.arcade.software/share/Q7nVvFA3GnJZtwdoOBSK>" %}
Add a GitLab connector in Harness
{% endembed %}

Perform the following steps to add a GitLab connector:

1. Open your Harness project.
2. In **Project Settings**, select **Connectors**.
3. Click **New Connector**, then select **GitLab**. The GitLab Connector settings appear.

### Overview

Configure the identity fields for the connector.

In **Name**, enter a name for the connector. Optionally, add a description and tags. Click **Continue**.

### Details

Configure the following details:

1. For **URL Type**, select one of:
   * **Account**: Connect to an entire GitLab account. The connector can be used for every repository in that account.
   * **Repository**: Connect to a single GitLab repository.
2. For **Connection Type**, select **HTTP** or **SSH**.
3. Enter the **GitLab Account URL** or **GitLab Repository URL**, depending on the URL Type you selected. For example:
   * Account URL (HTTP): `https://gitlab.com/GROUP_OR_USER`
   * Repository URL (HTTP): `https://gitlab.com/GROUP_OR_USER/REPO_NAME`
   * Repository URL (SSH): `git@gitlab.com:GROUP_OR_USER/REPO_NAME.git`
4. If you selected **Account** for URL Type, enter a **Test Repository**. Harness uses this repository only to validate the connection. You specify the actual repository to use when you reference the connector in a pipeline.
5. Click **Continue**.

### Credentials

Configure the credentials based on the connection type you selected:

* If you selected **HTTP**:
  * **Username and Password**: Enter your GitLab username. You can use plaintext or a [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md). For **Password**, select or create a new [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md) to store your GitLab account password.
  * **Username and Token**: Enter your GitLab username. You can use plaintext or a [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md). For **Personal Access Token**, select or create a new [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md) to store your GitLab personal access token.
  * **OAuth**: Click **Link to GitLab** to open a new browser tab and authorize access to your GitLab account.
* If you selected **SSH**:
  * Select or create a new [Harness SSH credential secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-ssh-secrets.md) to store your SSH key. The SSH credential's **Username** must be `git`.

Go to [GitLab connector settings reference](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/add-a-gitlab-connector/git-lab-connector-settings-reference.md) for detailed information on GitLab connection settings.

{% hint style="info" %}
**Enable API access for build status updates and triggers**

If you want to use Git Experience, send build or PR status updates back to GitLab, or to support Git event triggers and webhooks using the connector, select **Enable API access** and provide a [GitLab personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) as a [Harness encrypted text secret](https://developer.harness.io/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).
{% endhint %}

### Select Connectivity Mode

Select how Harness connects with GitLab:

* **Connect through Harness Platform**: Use a direct, secure communication between Harness and GitLab. All credentials are encrypted and stored in the Secret Manager configured in Harness. This connectivity mode is required for [Harness Cloud build infrastructure](https://developer.harness.io/docs/continuous-integration/use-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure/).
* **Connect through a Harness Delegate**: Harness communicates with GitLab through a Harness Delegate you install in your environment, behind your corporate firewall.

### Delegates Setup

If you selected **Connect through a Harness Delegate**, select either:

* **Use any available Delegate**: Harness selects an available delegate at runtime.
* **Only use Delegates with all of the following tags**: Select specific delegates for Harness to use with this connector.

Click **Save and Continue**.

### Test Connection

Click **Finish** after the connection test succeeds. The connector is listed in **Connectors**.

If the connection test fails:

* Confirm the account or repository URL matches the format for your selected URL Type and Connection Type.
* Confirm the personal access token has not expired and has the required scopes.
* If you are connecting through a delegate, confirm the delegate can reach your GitLab instance over the network.

{% hint style="info" %}
**Kubernetes delegate with self-signed certificates**

If this 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. Go to [Configure a Kubernetes build farm to use self-signed certificates](https://developer.harness.io/docs/continuous-integration/use-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates) for details.
{% endhint %}

***

## Sample YAML

The following example shows a YAML for the GitLab connector created in this guide.

<details>

<summary>YAML - GitLab connector</summary>

```yaml
connector:
  name: gitlab-connector # Replace with a name for your connector
  identifier: gitlabconnector # Replace with a unique identifier
  description: ""
  accountIdentifier: youraccountidentifier # Replace with your Harness account identifier
  orgIdentifier: default # Replace with your organization identifier, or remove for account scope
  projectIdentifier: yourprojectidentifier # Replace with your project identifier, or remove for org/account scope
  type: Gitlab
  spec:
    url: your-gitlab-repo-url # Replace with your GitLab account or repository URL
    authentication:
      type: Http # Use "Ssh" instead if you selected SSH as the Connection Type
      spec:
        type: UsernameToken
        spec:
          username: your-gitlab-username # Replace with your GitLab username, or a Harness expression referencing a secret
          tokenRef: your-personal-access-token # Replace with a reference to the Harness secret storing your personal access token
    executeOnDelegate: false # Set to true if you selected Connect through a Harness Delegate
    proxy: false
    ignoreTestConnection: false # Set to true only to skip connector preflight checks
    type: Repo # Use "Account" instead if you selected Account as the URL Type
```

</details>

For the full connector YAML schema, including how to skip connector preflight checks, go to [Create a connector using YAML](https://developer.harness.io/harness-platform/use-harness-platform/connectors/create-a-connector-using-yaml.md).

***

## Next steps

* [Use delegate selectors](https://developer.harness.io/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md): control which delegates can connect to this connector.
* [Add a secret manager](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management.md): store connector credentials in a secret manager instead of the Harness built-in secret manager.
