Skip to main content

​
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. 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

Anything defined in the GitLab REST API 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.
1

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 (sign-in required); on a self-managed instance, the same settings page lives under your own domain.
2

Go to Access Tokens

In the left sidebar, select Access Tokens.
3

Add a new token

Click Add new token.
4

Name the token and set an expiration

Enter a descriptive token name (for example “Serval Integration”) and an expiration date per your security policy.
5

Select scopes

Choose read_api for read-only workflows, or api for read/write.
6

Create and copy the token

Click Create personal access token and copy the value immediately - GitLab shows it only once.
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.
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.

​
Connect in Serval

1

Open the GitLab connect form

Add a new GitLab connection from your Serval integrations page.
2

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.
3

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.
4

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.
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).
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.

​
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).”
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your GitLab integration.