Docs · Connect your tools
Connect GitLab
StackWeaver reads, and never changes, one GitLab project once a day, through a Project or Personal Access Token you create yourself. It works against gitlab.com or any self-hosted GitLab instance. This guide says what is read, which permission the token needs, how to create one, and how to remove it.
Last reviewed: 6 November 2026 · Describes what is live in production on that date. A result is evidence of what the provider returned at a time, nothing more.
1. What it collects
Once a day StackWeaver calls the GitLab project's API with the token you paste. Each result is kept as an Evidence Object with a SHA-256 fingerprint (platform), including results that fail.
| Check (as shown in the portal) | What it looks at |
|---|---|
| Default branch protected | Whether the project's default branch has a protection rule |
| At least one approval required before merge | Whether merge requests need at least one approval (needs GitLab Premium or Ultimate; shown as not enabled on Free or Core) |
| Merge blocked unless pipeline succeeds | Whether merge requests can only merge after the pipeline succeeds |
| Force pushes blocked on the protected branch | Whether force pushes to the default branch are blocked |
| Open critical-severity vulnerabilities | The count of open critical-severity findings from any scanner (needs GitLab Premium or Ultimate) |
| Open high-severity vulnerabilities | The count of open high-severity findings from any scanner (needs GitLab Premium or Ultimate) |
2. What it does not do
- It does not read source code, commit contents, issues, merge request descriptions, or any data beyond the settings above.
- It cannot change anything: the token carries the read_api scope only.
- On GitLab Free or Core, the approvals and vulnerability checks show as not available rather than a false pass or fail.
- It does not say your project meets any standard. A result is what GitLab returned at a certain time.
3. The access it needs
One scope: read_api (GitLab), which reads the project's protected branch rules, merge settings, approval configuration and vulnerability summary.
Who can connect. In StackWeaver, a workspace owner or admin pastes the token. On GitLab's side, the token is created by whoever has at least the role GitLab requires to create a project or personal access token for that project; GitLab does not tell StackWeaver who that person is or what role they hold, so create the token with the read_api scope only and nothing else.
4. Connect steps
- In GitLab, open the project's Settings, Access tokens (a Project Access Token), or your own user Settings, Access tokens (a Personal Access Token).
- Create a token with the read_api scope only, and copy it — GitLab shows it once.
- In StackWeaver, open Evidence, the GitLab section, and paste the project's full URL (for example https://gitlab.com/group/project, or your self-hosted equivalent) together with the token.
- Press Test connection. StackWeaver records the result.
5. Reading the results
| Label | What it means |
|---|---|
| Pass | The provider returned data that meets the threshold at that time |
| Fail | The provider returned data that does not meet the threshold |
| Not enabled | There was nothing to check, or the feature needs a plan StackWeaver could not confirm |
| Could not check | StackWeaver could not read the data, or the check needs a higher plan than the account has |
6. Disconnect and revoke
- In StackWeaver, press Disconnect on the GitLab section. StackWeaver deletes the stored token.
- In GitLab, revoke the token yourself (Settings, Access tokens) — StackWeaver has no way to ask GitLab to revoke a token on your behalf.
What remains. Past evidence stays in your workspace as the audit trail. Disconnecting does not delete it.
7. Troubleshooting
| Message | What to do |
|---|---|
| Could not verify this project URL or token | Check the project URL is exact and the token has not expired or been revoked |
| This GitLab project is already connected to another StackWeaver workspace | Ask StackWeaver support if this is your project |
| At least one approval required before merge: Not enabled | This needs GitLab Premium or Ultimate; it is not available on Free or Core |
| Open critical/high-severity vulnerabilities: Not enabled | Vulnerability scanning needs GitLab Premium or Ultimate, and a scanner configured on the project |
Still stuck? Use the contact page.
Sources and method
Statements about GitHub and Okta link to their own documentation. Statements about StackWeaver link to the page that says them, or are recorded in a claims ledger with the file in StackWeaver's repository that they come from. See oureditorial policy. Spotted an error? Use the contact page.