sourcebot/docs/docs/connections/gitlab.mdx

---
title: Linking code from GitLab
sidebarTitle: GitLab
icon: GitLab
---

import GitLabSchema from '/snippets/schemas/v3/gitlab.schema.mdx'

Sourcebot can sync code from GitLab.com, Self Managed (CE & EE), and Dedicated.


## Examples

<AccordionGroup>
    <Accordion title="Sync individual projects">
        ```json
        {
            "type": "gitlab",
            "projects": [
                "my-group/foo",
                "my-group/subgroup/bar"
            ]
        }
        ```
    </Accordion>
    <Accordion title="Sync all projects in a group/subgroup">
        ```json
        {
            "type": "gitlab",
            "groups": [
                "my-group",
                "my-other-group/sub-group"
            ]
        }
        ```
    </Accordion>
    <Accordion title="Sync all projects in a self managed instance">
        <Note>This option is ignored if `url` is unset. See [connecting to a custom gitlab host](/docs/connections/gitlab#connecting-to-a-custom-gitlab-host).</Note>
        ```json
        {
            "type": "gitlab",
            "url": "https://gitlab.example.com",
            // Index all projects in this self-managed instance
            "all": true
        }
        ```
    </Accordion>
    <Accordion title="Sync all projects owned by a user">
        ```json
        {
            "type": "gitlab",
            "users": [
                "user-1",
                "user-2"
            ]
        }
        ```
    </Accordion>
    <Accordion title="Filter projects by topic">
        ```json
        {
            "type": "gitlab",
            // Sync all projects in `my-group` that have a topic that...
            "groups": [
                "my-group"
            ],
            // ...match one of these glob patterns.
            "topics": [
                "test-*",
                "ci-*",
                "k8s"
            ]
        }

        ```
    </Accordion>
    <Accordion title="Exclude projects from syncing">
        ```json
        {
            "type": "gitlab",
            // Include all projects in these groups...
            "groups": [
                "my-group",
                "my-other-group/sub-group"
            ]
            // ...except:
            "exclude": {
                // projects that are archived
                "archived": true,
                // projects that are forks
                "forks": true,
                // projects that match these glob patterns
                "projects": [
                    "my-group/foo/**",
                    "my-group/bar/**",
                    "my-other-group/sub-group/specific-project"
                ],
                // repos with topics that match these glob patterns
                "topics": [
                    "test-*",
                    "ci"
                ]
            }
        }
        ```
    </Accordion>
</AccordionGroup>


## Authenticating with GitLab

In order to index private projects, you'll need to generate a GitLab Personal Access Token (PAT). Create a new PAT [here](https://gitlab.com/-/user_settings/personal_access_tokens) and make sure you select the `read_api` scope:

![GitLab PAT Scope](/images/gitlab_pat_scopes.png)

Next, provide the PAT via the `token` property, either as an environment variable or a secret:

<Tabs>
    <Tab title="Environment Variable">
        <Note>Environment variables are only supported in a [declarative config](/docs/configuration/declarative-config) and cannot be used in the web UI.</Note>

        1. Add the `token` property to your connection config:
        ```json
        {
            "type": "gitlab",
            "token": {
                // note: this env var can be named anything. It
                // doesn't need to be `GITLAB_TOKEN`.
                "env": "GITLAB_TOKEN"
            }
            // .. rest of config ..
        }
        ```

        2. Pass this environment variable each time you run Sourcebot:
        ```bash
            docker run \
                -e GITLAB_TOKEN=<PAT> \
                /* additional args */ \
                ghcr.io/sourcebot-dev/sourcebot:latest
        ```
    </Tab>

    <Tab title="Secret">
        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>

        1. Navigate to **Secrets** in settings and create a new secret with your PAT:

        ![](/images/secrets_list.png)

        2. Add the `token` property to your connection config:

        ```json
        {
            "type": "gitlab",
            "token": {
                "secret": "mysecret"
            }
            // .. rest of config ..
        }
        ```

    </Tab>
</Tabs>

## Connecting to a custom GitLab host

To connect to a GitLab host other than `gitlab.com`, provide the `url` property to your config:

```json
{
    "type": "gitlab",
    "url": "https://gitlab.example.com"
    // .. rest of config ..
}
```

## Troubleshooting

- If you're seeing errors like `GitbeakerTimeoutError: Query timeout was reached` when syncing a large number of projects, you can increase the client's timeout by setting the `GITLAB_CLIENT_QUERY_TIMEOUT_SECONDS` environment variable. [#162](https://github.com/sourcebot-dev/sourcebot/issues/162)

## Schema reference

<Accordion title="Reference">
[schemas/v3/gitlab.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/gitlab.json)

<GitLabSchema />

</Accordion>