GitLab bridge

Capability: contract:tracker + contract:source-control + contract:change-request

Coverage: partial

Kind: implementation

Vendor: GitLab

Read-only client for the GitLab REST API v4.

This bridge implements a partial read-only foundation for repository metadata context under contract:source-control, issue listing and fetching under contract:tracker, and merge request discovery, diffs, commits, and CI pipeline status under contract:change-request. Partial adapters may implement named contract verbs, but they do not satisfy the complete contract and must not be advertised as complete/selectable backends. Write operations and issue/MR mutations remain out of scope for this foundation.

Prerequisites

• Runtime: Python 3.11+ via uv.
• CLIs: uv.
• Credentials / auth: GITLAB_TOKEN (Personal Access Token, OAuth Bearer token) or CI_JOB_TOKEN with API access. Tokens are optional for unauthenticated reads on public projects.
• Auth scheme override: GITLAB_AUTH_SCHEME (PrivateToken, Bearer, JobToken) can be set to override header selection explicitly.
• Network: Access to the configured GitLab instance; GITLAB_INSTANCE_URL defaults to https://gitlab.com.

Configuration

Set GITLAB_TOKEN in your environment:

export GITLAB_TOKEN="glpat-..."

For self-hosted instances (e.g. Debian Salsa, GNOME):

export GITLAB_INSTANCE_URL="https://salsa.debian.org"

To explicitly force an authentication scheme (e.g. OAuth Bearer token vs Private Token):

export GITLAB_AUTH_SCHEME="Bearer"

Operations

See tool.md for the full operations catalogue and contract mapping.

Usage

List open issues for a project:

uv run --project tools/gitlab magpie-gitlab issue list <project>

Get a merge request diff:

uv run --project tools/gitlab magpie-gitlab mr diff <project> <mr_iid>