> ## Documentation Index
> Fetch the complete documentation index at: https://sourcebot-whoisthey-language-model-input-modalities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Linking code from GitLab

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

If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first.

## Examples

<AccordionGroup>
  <Accordion title="Sync individual projects">
    ```json theme={null}
    {
        "type": "gitlab",
        "projects": [
            "my-group/foo",
            "my-group/subgroup/bar"
        ]
    }
    ```
  </Accordion>

  <Accordion title="Sync all projects in a group/subgroup">
    ```json theme={null}
    {
        "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 theme={null}
    {
        "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 theme={null}
    {
        "type": "gitlab",
        "users": [
            "user-1",
            "user-2"
        ]
    }
    ```
  </Accordion>

  <Accordion title="Filter projects by topic">
    ```json theme={null}
    {
        "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 theme={null}
    {
        "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 are owned by users (not groups)
            "userOwnedProjects": 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:

<img src="https://mintcdn.com/sourcebot-whoisthey-language-model-input-modalities/UI3at4lP3VZBMCMb/images/gitlab_pat_scopes.png?fit=max&auto=format&n=UI3at4lP3VZBMCMb&q=85&s=cb19f539df0569a556dd526c1d83a23b" alt="GitLab PAT Scope" width="1658" height="424" data-path="images/gitlab_pat_scopes.png" />

Next, provide the PAT via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property:

<Tabs>
  <Tab title="Environment Variable">
    1. Add the `token` property to your connection config:

    ```json theme={null}
    {
        "type": "gitlab",
        "token": {
            // note: this env var can be named anything. It
            // doesn't need to be `GITLAB_TOKEN`.
            "env": "GITLAB_TOKEN"
        },
        // At least one of the following is required to specify which projects to sync:
        "projects": ["my-group/myProject"],
        // "groups": ["my-group"],
        // "users": ["my-user"],
        // "all": true (self-managed only)
    }
    ```

    2. Pass this environment variable each time you run Sourcebot:

    ```bash theme={null}
        docker run \
            -e GITLAB_TOKEN=<PAT> \
            /* additional args */ \
            ghcr.io/sourcebot-dev/sourcebot:latest
    ```
  </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 theme={null}
{
    "type": "gitlab",
    "url": "https://gitlab.example.com",
    // At least one of the following is required to specify which projects to sync:
    "projects": ["my-group/myProject"],
    // "groups": ["my-group"],
    // "users": ["my-user"],
    // "all": true
}
```

## 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)
* If you're seeing errors like `TypeError: fetch failed` when fetching user/project info, it may be that Sourcebot is refusing to connect to your self-hosted GitLab instance due to unrecognized SSL certs. Try setting the `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable or providing Sourcebot your certs through the `NODE_EXTRA_CA_CERTS` environment variable.

## Schema reference

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

  ```json theme={null}
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "GitlabConnectionConfig",
    "properties": {
      "type": {
        "const": "gitlab",
        "description": "GitLab Configuration"
      },
      "token": {
        "description": "An authentication token.",
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "env": {
                "type": "string",
                "description": "The name of the environment variable that contains the token."
              }
            },
            "required": [
              "env"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "googleCloudSecret": {
                "type": "string",
                "description": "The resource name of a Google Cloud secret. Must be in the format `projects/<project-id>/secrets/<secret-name>/versions/<version-id>`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets"
              }
            },
            "required": [
              "googleCloudSecret"
            ],
            "additionalProperties": false
          }
        ]
      },
      "url": {
        "type": "string",
        "format": "url",
        "default": "https://gitlab.com",
        "description": "The URL of the GitLab host. Defaults to https://gitlab.com",
        "examples": [
          "https://gitlab.com",
          "https://gitlab.example.com"
        ],
        "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$"
      },
      "all": {
        "type": "boolean",
        "default": false,
        "description": "Sync all projects visible to the provided `token` (if any) in the GitLab instance. This option is ignored if `url` is either unset or set to https://gitlab.com ."
      },
      "users": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "List of users to sync with. All projects owned by the user and visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property."
      },
      "groups": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "my-group"
          ],
          [
            "my-group/sub-group-a",
            "my-group/sub-group-b"
          ]
        ],
        "description": "List of groups to sync with. All projects in the group (and recursive subgroups) visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property. Subgroups can be specified by providing the path to the subgroup (e.g. `my-group/sub-group-a`)."
      },
      "projects": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "my-group/my-project"
          ],
          [
            "my-group/my-sub-group/my-project"
          ]
        ],
        "description": "List of individual projects to sync with. The project's namespace must be specified. See: https://docs.gitlab.com/ee/user/namespace/"
      },
      "topics": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1,
        "description": "List of project topics to include when syncing. Only projects that match at least one of the provided `topics` will be synced. If not specified, all projects will be synced, unless explicitly defined in the `exclude` property. Glob patterns are supported.",
        "examples": [
          [
            "docs",
            "core"
          ]
        ]
      },
      "exclude": {
        "type": "object",
        "properties": {
          "forks": {
            "type": "boolean",
            "default": false,
            "description": "Exclude forked projects from syncing."
          },
          "archived": {
            "type": "boolean",
            "default": false,
            "description": "Exclude archived projects from syncing."
          },
          "userOwnedProjects": {
            "type": "boolean",
            "default": false,
            "description": "Exclude user-owned projects from syncing."
          },
          "projects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [],
            "examples": [
              [
                "my-group/my-project"
              ]
            ],
            "description": "List of projects to exclude from syncing. Glob patterns are supported. The project's namespace must be specified, see: https://docs.gitlab.com/ee/user/namespace/"
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of project topics to exclude when syncing. Projects that match one of the provided `topics` will be excluded from syncing. Glob patterns are supported.",
            "examples": [
              [
                "tests",
                "ci"
              ]
            ]
          }
        },
        "additionalProperties": false
      },
      "revisions": {
        "type": "object",
        "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.",
        "properties": {
          "branches": {
            "type": "array",
            "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "main",
                "release/*"
              ],
              [
                "**"
              ]
            ],
            "default": []
          },
          "tags": {
            "type": "array",
            "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "latest",
                "v2.*.*"
              ],
              [
                "**"
              ]
            ],
            "default": []
          }
        },
        "additionalProperties": false
      },
      "enforcePermissions": {
        "type": "boolean",
        "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing"
      },
      "enforcePermissionsForPublicRepos": {
        "type": "boolean",
        "default": false,
        "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing"
      }
    },
    "required": [
      "type"
    ],
    "additionalProperties": false
  }
  ```
</Accordion>