Connect GitLab

Specsight reads GitLab code through an access token you create in GitLab and paste into Specsight. There is no app to install, and GitLab.com and self-managed instances both work.

The token is stored encrypted and used only to read your code and manage Specsight’s webhooks. It never writes to your code.

First-run setup can connect GitLab for you. This article covers the GitLab page you use afterwards. Open Integrations in the org rail, then GitLab.

Before you start

Prepare the account and the token in GitLab first. The page shows the same checklist above the form.

1. Use a dedicated GitLab account that is a member of only the groups Specsight should watch, with the Maintainer role. That role is what lets Specsight set up its webhooks
2. Create an access token for that account in GitLab. Choose Fine-grained token, limit it to those groups under Group and project access, and set an expiry

Then, under Add resource permissions, tick exactly these:

GitLab allows an expiry up to a year, and shows the token only once, so copy it straight away. Specsight checks the token with GitLab and refuses one missing any permission, or carrying more. Create it with exactly this list.

Older GitLab or group access tokens

Older GitLab (before 19.2) and group access tokens have no fine-grained option. Choose Legacy token and tick the api scope instead. That scope is broader than Specsight needs, which is why the dedicated account matters.

Self-managed instances

Self-managed instances must use https and be reachable from the public internet, because Specsight reads the code from the cloud. It has no fixed outbound IP addresses, so it cannot be allow-listed or reach an instance behind a VPN. The instance must also allow outgoing webhooks to specsight.app.

Connect

1. In the Connection card, keep Instance URL as https://gitlab.com or enter the https address of your instance
2. Paste the token into Access token
3. Click Connect GitLab

If the token is refused

Nothing is stored until the token passes every check. The error names the fix:

• GitLab rejected the token. Check it was copied completely. — GitLab does not accept the token as pasted
• That token has been revoked or has expired. — create a new one in GitLab
• The token is missing permissions. — followed by the tab and the exact permissions to tick. A fine-grained token that skipped the User tab is told which permission to add there
• The token grants more than Specsight uses — followed by the extra permissions. Create a new token with only the permissions listed
• The token has no group or project access. — add the groups Specsight should watch under Group and project access
• The token needs the api scope so Specsight can set up webhooks. — a legacy token without api
• Could not reach the GitLab instance. It must be accessible from the public internet. — the instance is not reachable from outside your network

Replace the token

Click Replace token in the Connection card. The form reopens with your instance URL filled in; paste the new token and click Connect GitLab.

Disconnect

Click Disconnect in the Connection card and confirm with Yes, disconnect. Specsight deletes the stored token and asks GitLab to remove the webhooks it created. Syncing stops for every project on this connection, and nothing already in your spec changes.

Each affected project then shows a banner: Specsight has lost access to this repository, so it has stopped following releases. Reconnect it to resume syncing. Connect again and those projects resume, as long as the new token can reach them. A project the token cannot reach says so on its banner, and Retry checks that repository again.

Token expiry and rejection

GitLab tokens have a fixed lifetime, so every connection needs a fresh token eventually. Specsight checks the token with GitLab once a day and tells you before it lapses.

• Token expiring — from 30 days before the expiry date, Specsight says the token is expiring soon
• Reconnect needed — GitLab no longer accepts the token

Specsight emails when 30, 7 and 1 days remain, with a Replace the token button.

When GitLab rejects the token, one email goes out with a Reconnect GitLab button. Until you replace it, releases do not sync. Nothing already in your spec is affected.