> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/get-started/onboarding-to-ox/source-control/gitlab-1/gitlab-token.md).

# GitLab Token

Use this method to connect GitLab to OX by using a Personal Access Token (PAT). This method authenticates OX with your GitLab account and allows OX to discover and scan the projects that are accessible to that account.

### Before you begin

Verify that:

* You have permission to configure connectors in OX.
* You have permission to create Personal Access Tokens in GitLab.
* The GitLab account that owns the token has the Maintainer role on every project OX scans. This role is required to manage webhooks and approval rules used by Git Posture.
* It is recommended to use a dedicated service account with the Maintainer role at the top-level GitLab group containing the projects you want OX to scan.

### Step 1: Create a Personal Access Token

1. Sign in to GitLab.
2. Go to **User Settings > Access Tokens**.
3. Select **Add new token**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-e8eab82e51e5cee90589b76957e947d7d49bbbd5%2FGitlab_token1.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

4. Enter a name for the token.
5. Optional: Specify an expiration date.
6. Select the following scopes:
   * `api`
   * `read_user`
7. Select **Create personal access token**.
8. Copy the generated token.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-32aee34a8a180735b5cfcb134abd27eb61832717%2FGitlab_token2.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

> **Note**
>
> GitLab displays the token only once. Store it securely before leaving the page.

### Step 2: Connect GitLab to OX

1. In OX, go to **Settings > Connections**.
2. Select **GitLab**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-402c5006b4da521bf4581c981073751c8b954730%2FGitlab_token%20(1).png?alt=media" alt="" width="512"><figcaption></figcaption></figure>

3. Open the **Token** tab.
4. Configure the connection.

| Parameter                   | Description                                                                                                                                                                                                                                                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitLab Host URL**         | The URL of your GitLab instance. For GitLab.com, enter `https://gitlab.com`. For a self-managed GitLab instance, enter your GitLab server URL.                                                                                                                                                                                                           |
| **Token**                   | The Personal Access Token (PAT) that you created in GitLab.                                                                                                                                                                                                                                                                                              |
| **Connection Name**         | A unique name for the connection.                                                                                                                                                                                                                                                                                                                        |
| **OX Broker**               | Enable this option to connect GitLab through an OX Broker instead of a direct connection. When enabled, OX routes communication through the broker, allowing access to GitLab instances that are not directly reachable from the internet. After enabling the toggle, provide the broker connection details as described in the OX Broker documentation. |
| **Bypass SSL Verification** | Enable to skip SSL certificate validation. Use only if your environment uses self-signed or otherwise untrusted certificates. Not recommended because it reduces connection security.                                                                                                                                                                    |

5. Select **Verify Connectivity**.
6. Select **Connect**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/get-started/onboarding-to-ox/source-control/gitlab-1/gitlab-token.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
