> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Connect GitLab to Serval with a personal access token so workflows can call the full GitLab REST API on gitlab.com or your self-managed instance.

## About GitLab

GitLab is a DevOps platform for source control, issues, merge requests, and CI/CD. Serval connects to gitlab.com or any self-managed GitLab instance using a GitLab personal access token: you paste it in once, Serval stores it encrypted and attaches it to every request a workflow makes, using GitLab's standard private token header. The instance domain you enter at connect time becomes the base for every request, so one integration covers both GitLab SaaS and self-hosted deployments. The integration is currently flagged as **Beta** in the connect UI.

**Authentication:** GitLab personal access token, plus the instance domain. There is no OAuth or sign-in flow.

**Data sync:** No background sync and no webhooks. Serval contacts GitLab only on demand - when a workflow runs, and when health checks run after connecting or from the integration settings page.

## What the GitLab integration enables

| Capability                         | Description                                                                                                                                                                                           |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full GitLab REST API access        | Workflows use a single generic GitLab API request action to call any part of the GitLab REST API v4 - roughly 1,300+ typed paths covering the full API surface, generated from GitLab's OpenAPI spec. |
| Work with projects and groups      | List and read projects and groups. Identifiers can be numeric IDs or URL-encoded full paths (for example my-group%2Fmy-project).                                                                      |
| Automate issues and merge requests | Read and write issues, merge requests, pipelines, and related resources through the same API request action (writes require the api token scope).                                                     |
| SaaS or self-managed instances     | Point the connection at gitlab.com or any self-hosted GitLab domain - the same integration works against either deployment model.                                                                     |

Anything defined in the [GitLab REST API](https://docs.gitlab.com/api/rest/) can be accessed through Serval.

## Get your credentials

Serval needs a **GitLab personal access token**. Choose the scope based on what your workflows will do: **read\_api** for read-only workflows, or **api** if workflows will create or update GitLab resources. GitLab's official guide is here: [GitLab personal access tokens documentation](https://docs.gitlab.com/user/profile/personal_access_tokens/).

<Steps>
  <Step title="Open your token settings">
    In GitLab, open your avatar menu and select **Edit profile**. On gitlab.com you can go directly to the [personal access token settings page](https://gitlab.com/-/user_settings/personal_access_tokens) (sign-in required); on a self-managed instance, the same settings page lives under your own domain.
  </Step>

  <Step title="Go to Access Tokens">
    In the left sidebar, select **Access Tokens**.
  </Step>

  <Step title="Add a new token">
    Click **Add new token**.
  </Step>

  <Step title="Name the token and set an expiration">
    Enter a descriptive token name (for example "Serval Integration") and an expiration date per your security policy.
  </Step>

  <Step title="Select scopes">
    Choose **read\_api** for read-only workflows, or **api** for read/write.
  </Step>

  <Step title="Create and copy the token">
    Click **Create personal access token** and copy the value immediately - GitLab shows it only once.
  </Step>
</Steps>

<Warning>
  Create the token on the same GitLab instance you plan to connect. A token issued on gitlab.com will not work against a self-managed instance, and vice versa.
</Warning>

<Tip>
  If you set an expiration date, note it down. An expired token fails silently until a health check or workflow run surfaces the error - plan to rotate before it lapses.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the GitLab connect form">
    Add a new GitLab connection from your Serval integrations page. The integration is labeled **Beta**.
  </Step>

  <Step title="Enter the Instance Domain (optional)">
    The **Instance Domain** field is a text field with the placeholder "gitlab.com". Leave it blank if you use GitLab SaaS - it defaults to gitlab.com. If you run a self-managed instance, enter its domain. The field is not marked required and applies no format validation.
  </Step>

  <Step title="Paste your Personal Access Token">
    The **Personal Access Token** field is a password field. The form does not mark it required and will accept an empty submission, but the connection cannot work without it - every API call fails until a valid token is saved.
  </Step>

  <Step title="Submit the form">
    Submit the connection. If something goes wrong, the connect form on an application page shows the toast "Failed to connect service"; the underlying error reads "Failed to install integration", with details appended when GitLab or Serval returns any.
  </Step>
</Steps>

<Note>
  Serval does not test or format-check either field when you save - a blank token or a mistyped domain is accepted at save time and only surfaces when the health checks run. Run them right after connecting (see below).
</Note>

<Tip>
  After saving, the token is displayed masked - bullet characters plus its last 4 characters - with a pencil icon next to it. Clicking the pencil opens an empty "Enter new value" box for the replacement token. When you later edit the connection, leaving the token field untouched or blank keeps your existing stored token, and leaving the Instance Domain blank keeps the existing domain. To rotate the token, paste the complete new value into the field, save, and re-run the health checks.
</Tip>

## Verifying the connection

The connection ships two health checks that make live calls to your GitLab instance. They run automatically after connecting (if enabled) and on demand from the integration settings page:

* **Validate GitLab API Connection** - makes a lightweight call to your instance to confirm the personal access token authenticates against the configured domain. Success: "Successfully connected to GitLab API. Instance version: \[version]." Failure: "Unable to connect to GitLab API. Please verify your personal access token is valid and your instance domain is correct."
* **List GitLab Projects** - lists a small sample of projects (up to 5) to confirm the token actually has API read access. Success: "Successfully listed GitLab projects. Found \[number] project(s)." A count of 0 still passes - it means the token works but its user has no visible projects. Failure: "Unable to list GitLab projects. Please verify your token has the appropriate scopes (read\_api or api)."

<Tip>
  If **Validate GitLab API Connection** passes but **List GitLab Projects** fails, the token is reaching the right instance but lacks API read access. Recreate the token with the **read\_api** or **api** scope and update the connection.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The token must match the instance domain">
    The Instance Domain is the base for every request, and tokens are instance-specific: a token issued on gitlab.com will not authenticate against a self-managed domain, and vice versa. If **Validate GitLab API Connection** fails, confirm both that the token is valid (not expired or revoked) and that the Instance Domain matches the instance where the token was created.
  </Accordion>

  <Accordion title="A connection can save successfully but still not work">
    Neither form field is marked required and there is no format validation, so a blank token or a malformed domain is accepted and the connection is created anyway. Problems only surface when the health checks run - treat green health checks, not a successful form submit, as confirmation the connection works.
  </Accordion>

  <Accordion title="Token scope limits what workflows can do">
    The **read\_api** scope is sufficient for listing and reading projects, groups, issues, and merge requests. The **api** scope is required for workflows that create or update GitLab resources. The **List GitLab Projects** health check fails with a scope hint ("Please verify your token has the appropriate scopes (read\_api or api).") when the token authenticates but lacks API read access.
  </Accordion>

  <Accordion title="Workflow request paths are passed through exactly as written">
    A note for whoever builds workflows on this connection: Serval does not add GitLab's version prefix to request paths, so every path must start with /api/v4/ as written. Project and group identifiers can be numeric IDs or URL-encoded full paths such as my-group%2Fmy-project. List results come back as plain arrays, and pagination is page-based - pass the page and per\_page query parameters and loop until an empty page.
  </Accordion>

  <Accordion title="Rotating your personal access token">
    Edit the GitLab connection, click the pencil icon next to the masked token, and paste the complete new token into the "Enter new value" box, then save. Saving with the token field blank keeps the previously stored token, so a rotation only takes effect when you actually enter the new value. If the update fails, the settings page shows "Failed to update configuration". Re-run the health checks afterward to confirm the new token works.
  </Accordion>

  <Accordion title="The integration is in beta">
    GitLab is flagged as **Beta** in the connect UI. Behavior and capabilities may evolve - if you hit something unexpected, contact support.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your GitLab integration.