GitLab

GitLab connects with a personal access token and gives you the full git-host feature set: merge requests, pipelines, and assigned issues in the Inbox. Both GitLab.com and self-managed instances are supported.

Note

GitLab calls them merge requests; Birch calls them PRs everywhere — in the UI, the Inbox, and the CLI. This page follows Birch’s naming.

Creating the token

In Settings → Integrations, click the GitLab tile and then Create a token on GitLab ↗. The link opens https://gitlab.com/-/user_settings/personal_access_tokens?name=Birch&description=Birch&scopes=api — or the same page on your own instance if you have typed a custom base URL — with the token named Birch and the api scope already ticked.

The form’s Token permissions list names the one scope Birch needs:

Scope	Used for
api	Every read and write: merge requests, approvals, pipelines, issues and their status

• read_api is not enough: every write would fail.
• A group that enforces fine-grained tokens rejects legacy scopes like api.

Warning

Verify & connect only checks whose token it is, so a token with too narrow a scope still connects — and then fails when Birch syncs or writes.

Adding the account

1. Open Settings → Integrations (⌘, / Ctrl+,) and click the GitLab tile.

2. Fill the form:

   Field	What to enter
   Personal access token	Your glpat-… token with the api scope
   Custom base URL	Leave empty for gitlab.com. For self-managed GitLab, enter your instance’s root URL

3. Click Verify & connect. Birch verifies the token before storing it; on success the account appears with a Connected badge and Sync now / Remove buttons.

The token is stored in the system keychain, and multiple GitLab accounts can be connected side by side. See the providers overview for the shared connection model.

What you get

• PRs (merge requests) — on the repository page and the workspace PR card, with state and checks; pipeline status surfaces wherever Birch shows a PR’s checks. Review requests and activity on your PRs land in the Inbox.
• Assigned issues — synced into the Inbox Tasks tab, with images from issue descriptions downloaded as thumbnails and handed to the agent when you start a workspace from the task.
• Issue status updates on workspace launch / PR creation — see status transitions.
• AI code review of new PRs — see AI code review, an Anthropic API feature.

Supported PR operations

• Create a PR from a workspace (with Create as draft) or via birch pr create — see Create a pull request.
• Check out a PR into a new workspace: birch pr checkout <url-or-id>.
• Merge with birch pr merge <url-or-id> (--strategy, --delete-source).
• List PRs with birch pr list.

Full flag reference: CLI — pr.

Troubleshooting

• Verification fails — the token is likely revoked or was pasted incompletely; recreate it and reconnect.
• Sync or PR writes fail on a connected account — check the scope: the token needs api. A read_api token connects but cannot write.
• Creating, merging, closing, drafting or reviewing a PR is refused — Birch shows GitLab’s own reason followed by what to check. On a 403: “GitLab refused this: the token may lack the api scope (read_api can’t write), or your project role may not allow it. Check Settings > Integrations.” On a 401 it says the token may have expired or been revoked — or that you may not be allowed to merge or approve this merge request (or already approved it), since GitLab answers those with a 401 too.
• Wrong instance URL — leave the base URL empty for gitlab.com. For self-managed instances, enter the instance root (for example https://gitlab.example.com), not a group or project URL.
• Expired token — self-managed GitLab instances often enforce token expiry; recreate the token via the Create a token on GitLab ↗ link and reconnect.
• Rate limiting — Birch syncs on a ~10-minute cadence to keep request volume low; if your instance throttles anyway, the next sync cycle retries.