GitLab

Proxy for the GitLab REST API via the managed gateway.

What this connector does

Gives agents gated access to a GitLab instance (SaaS or self-hosted) for:

• Listing users, projects, merge requests.
• Creating and editing merge requests.
• Commenting on merge requests.
• Minting project access tokens.
• Listing container-registry repositories and tags.

All operations are gated by PBAC policy. Every call flows: agent → gateway → /introspect (with this connector's resource_type) → OPA decision → GitLab API → response.

The connector supports two auth modes, chosen per managed resource at install time:

• Per-user passthrough (idp_passthrough, recommended) — the gateway forwards each calling user's own GitLab OAuth token (captured when they log in to PolicyArc through the GitLab IdP). GitLab enforces its own project membership and permissions, and its audit trail shows the real person.
• Shared service token (static) — every call uses one operator-held personal/project/group access token via the PRIVATE-TOKEN header. PolicyArc still enforces per-user policy and audit in front, but GitLab sees a single service identity.

Prerequisites

• The base URL of your GitLab instance (defaults to https://gitlab.com).
• Passthrough mode only: a GitLab IdP registered in PolicyArc with provider key gitlab (use the GitLab preset in the IdP setup wizard). The OAuth application on your GitLab instance must request the api scope in addition to the OIDC login scopes (openid profile email). Users must log in to PolicyArc through that GitLab IdP — the gateway replays the token captured at login.
• Static mode only: a GitLab access token that has enough permission for the operations you want to gate. Options:
  • Personal Access Token — scoped to one user; simplest for PoC.
  • Project Access Token — scoped to one project; recommended for production if the agent only needs one project.
  • Group Access Token — scoped to a group of projects.

Install

Pick the auth mode in the install form's Authentication field (defaults to idp_passthrough). The access-token field only appears when static is selected; passthrough installs need no secret.

1. Provision the credential (static mode)

For static mode, create a GitLab access token with the minimum scopes you need. For MR automation:

Operation	Minimum GitLab scope
List projects/MRs/notes	read_api
Create/edit MRs, post comments	api
Create project access tokens	api + project Owner/Maintainer
Container registry	read_registry

Put the token in an environment variable the PBAC AS can read (static mode only):

export GITLAB_PRIVATE_TOKEN="glpat-..."

2. Install the connector

From the admin UI (once the v1 installer ships):

1. Resources → Add → GitLab
2. Fill in the wizard:
   • GitLab base URL — https://gitlab.com or your self-hosted URL.
   • Access token (env var name) — the name of the env var holding the token (e.g. GITLAB_PRIVATE_TOKEN), not the token itself. The AS reads the env var at request time. (Static mode only — this field is hidden when idp_passthrough is selected.)
3. Install.

The admin UI reads setup_fields directly from this connector's manifest — same fields shown below in the Setup fields reference.

3. Verify

Request a token with a GitLab scope:

curl -X POST https://<your-as>/token \
  -u "<agent-client-id>:<agent-client-secret>" \
  -d "grant_type=client_credentials&scope=gitlab:read"

Call through the gateway:

curl https://<your-as>/gateway/identos.gitlab/api/v4/projects?search=acme \
  -H "Authorization: Bearer <token>"

A successful 200 with the project list confirms: token issued → introspect allowed → gateway proxied → upstream responded.

What can go wrong

Symptom	Cause	Fix
401 from GitLab (static mode)	GITLAB_PRIVATE_TOKEN env var not set or wrong	Check the AS process environment; confirm echo $GITLAB_PRIVATE_TOKEN resolves in the container.
403 from the gateway	Agent lacks the required scope	Request a token with gitlab:read, gitlab:write, or gitlab:admin matching the route.
404 at the gateway	Wrong path	Gateway path is /gateway/identos.gitlab/<GitLab REST path> — GitLab paths start with /api/v4/....
Agent sees an empty project list (static mode)	The PAT's user is in no projects	Use a wider-scope token or add the user to the target projects.
502 "no stored IdP token" (passthrough mode)	The caller never logged in through the gitlab IdP (or used client_credentials, which has no user context)	Re-authenticate via GitLab.
GitLab 401/403 upstream (passthrough mode)	The captured token expired and refresh failed, or the OAuth app wasn't granted api	Check the IdP registration's scopes.

Scopes

Scope	Meaning	Routes
gitlab:read	Read-only operations	list/get projects, MRs, notes, registries
gitlab:write	Mutating operations	create/edit MRs, post MR comments
gitlab:admin	Privileged operations	create project access tokens

Policy authors can write rules targeting input.resource.type == "urn:connector:identos:gitlab". Per-project rules use the resource_id (gitlab://projects/{project_id}).

Setup fields

Field	Required	Default	Purpose
base_url	yes	https://gitlab.com	GitLab base URL (SaaS or self-hosted).
upstream_auth.type	yes	idp_passthrough	Authentication — idp_passthrough (per-user, default) or static (shared token).
token_env	conditional	—	Name of the env var holding the access token (not the token itself). Static mode only; hidden when idp_passthrough is selected.

MCP tools

When the managed gateway's MCP aggregator is enabled, this connector exposes the following tools to agents:

Tool	Scope	Description
list_users	gitlab:read	Look up users — username for exact lookup (resolves ids for assignee/reviewer fields), search for fuzzy.
list_projects	gitlab:read	List projects, filtered by search, membership, ownership, visibility, min access level, topic or activity.
get_project	gitlab:read	Get a project by ID or URL-encoded path, optionally with license and statistics.
list_merge_requests	gitlab:read	List MRs on a project, filtered by scope, author, assignee, reviewer, labels, milestone, branches, text or date range.
create_merge_request	gitlab:write	Open a new MR, including assignees, reviewers, labels, milestone and merge options.
list_merge_request_notes	gitlab:read	List comments on an MR, with sort order.
create_merge_request_note	gitlab:write	Add a comment to an MR, optionally internal. body executes GitLab quick actions — see Comment bodies carry quick actions.
edit_merge_request	gitlab:write	Update MR title/description/state, assignees, reviewers, labels (replace or add/remove), target branch, milestone, squash, remove-source-branch, discussion lock.
create_project_access_token	gitlab:admin	Mint a project access token. Defaults are not least privilege — see Access-token defaults.
list_registry_repositories	gitlab:read	List container registry repositories on a project.
list_registry_tags	gitlab:read	List tags in a registry repository.
get_registry_tag	gitlab:read	Get a registry tag's details, including created_at (publish date), digest, and size.
list_releases	gitlab:read	List releases for a project (newest first).
get_release	gitlab:read	Get a single release by tag name.

Each tool's input schema is embedded in the manifest and forwarded verbatim to MCP clients.

What the scope layer does and does not promise

Worth being explicit, because the connector's tool list can read like a capability boundary and it is not one.

A route is the unit of authorization. Each route pairs one (method, pattern) with one scope, and that pair is what gitlab:read / gitlab:write / gitlab:admin gates. Arguments are then mapped onto the upstream request and are not validated against the route's input_schema.

Two things follow, both intended:

• A new GitLab parameter works without a code change. The route forwards the request body as-is, so the day GitLab adds a field it is already usable over /gateway/{name}/**. Declaring it in input_schema is what makes it discoverable — a schema-driven MCP client only sends what the schema advertises, so an undeclared field is unreachable for an agent even though the transport already carries it. That asymmetry is the whole reason this connector's schemas are kept wide: edit_merge_request once declared only title/description/state_event, and agents therefore treated assignees and reviewers as impossible when the endpoint had always accepted them.
• Leaving a field out is not a restriction. created_at and merge_request_diff_head_sha are undeclared here so they are not offered, but a caller that sends one anyway has it proxied. Treat the tool list as an affordance, not a wall.

How to actually restrict an argument

Policy, not the schema. Rules see the whole argument object at input.context.rs_context.tool_arguments. Sketch, in the operator namespace because what to restrict is tenant-specific:

package pbac.operator.connectors["identos.gitlab"]

import rego.v1

_is_gitlab if input.resource.type == "urn:connector:identos:gitlab"

# rs_context is absent at token issuance and carries resource_name on a gateway
# data-plane call. Any rule that fires on the ABSENCE of an argument needs this
# guard, or it denies every token request for the resource type.
_is_gateway_call if input.context.rs_context.resource_name

_args := input.context.rs_context.tool_arguments

deny contains msg if {
	_is_gitlab
	_is_gateway_call
	input.action.method == "POST"
	endswith(input.action.path, "/notes")
	"created_at" in object.keys(_args)
	msg := "gitlab: backdating notes is not permitted"
}

object.keys(_args) rather than _args.created_at matters: a missing key is undefined, and not _args.created_at would silently skip the rule.

GitLab behaviours an operator should know

Three facts about GitLab that the scope names do not convey. None is a defect in this connector; each is worth a deliberate decision.

Access-token defaults are not least privilege

create_project_access_token sits behind gitlab:admin, but GitLab's defaults are the problem: omit access_level and you get a Maintainer (40) token, and omit expires_at and you get the maximum lifetime the instance allows. Both are declared on the tool, which is what lets a caller ask for less — and lets policy see what was asked. Declaring access_level also makes Owner (50) requestable where it previously was not, so if you allow this tool, cap it:

deny contains msg if {
	_is_gitlab
	_is_gateway_call
	input.action.method == "POST"
	endswith(input.action.path, "/access_tokens")
	object.get(_args, "access_level", 40) > 30
	msg := "gitlab: project access tokens are capped at Developer (30)"
}

The token this route mints lives outside PolicyArc — no introspection, no revocation, no audit — so its role and lifetime are the only controls you get.

Comment bodies carry quick actions

GitLab executes leading slash commands in a note body as the commenting user. So create_merge_request_note can assign, label, close, approve or merge when body starts with /assign, /close, /approve, /merge. This connector exposes no merge route; the note body reaches past that, by GitLab's design.

GitLab's own permissions still apply — a quick action cannot exceed what the calling credential could do directly. The thing to plan for is narrower: the scope says "comment" and the effect can be "merge", and a command-only body applies the command without posting a comment, so the MR history shows the effect and not the instruction. In static mode every caller shares one operator token, so its role bounds everyone.

Not shipped as connector policy, because a legitimate comment may reasonably begin with /. If that trade is wrong for your tenant:

deny contains msg if {
	_is_gitlab
	_is_gateway_call
	input.action.method == "POST"
	endswith(input.action.path, "/notes")
	some line in split(_args.body, "\n")
	startswith(trim_space(line), "/")
	msg := "gitlab: quick actions are not permitted in comment bodies"
}

Check every line, not just the first — GitLab scans the whole body.

list_users search widens under an admin token

search matches name, username and public email for a normal caller. Under an administrator token — which static mode often holds — GitLab widens it to match private email addresses. Prefer username for exact lookups, and scope the static-mode token to the least privileged account that does the job.

Example policy

Block MR creation on a sensitive project unless the caller belongs to the release-managers group:

package pbac.operator.connectors["identos.gitlab"]

deny contains msg if {
  input.resource.type == "urn:connector:identos:gitlab"
  input.action.method == "POST"
  endswith(input.action.path, "/merge_requests")
  input.resource.id == "gitlab://projects/release-critical"
  not "release-managers" in input.subject.groups
  msg := "only release-managers can open MRs against release-critical"
}

This rule lives in the operator namespace (not this connector's) because "which group is allowed" is tenant-specific.

Reference

• Manifest: connectors/identos.gitlab/connector.v1.json in the repo.
• Upstream API docs: docs.gitlab.com/ee/api
• Access token types: docs.gitlab.com/ee/user/profile/personal_access_tokens

Manifest reference

• ID: identos.gitlab
• Version: 1.4.0
• Resource type: urn:connector:identos:gitlab
• Capabilities: mcp

Supported auth modes

Type	Details
idp_passthrough	requires IdP gitlab
static	scheme header; header PRIVATE-TOKEN; setup fields: token_env

Setup fields

ID	Label	Default	Secret?	Notes
base_url	GitLab base URL	https://gitlab.com	no	placeholder: https://git.example.com
upstream_auth.type	Authentication	idp_passthrough	no	idp_passthrough forwards each user's own GitLab OAuth token (recommended). static uses a shared personal/project/group access token via the PRIVATE-TOKEN header.
token_env	Access token	—	yes	Pick a secret holding a GitLab personal, project, or group access token. Required only for the static auth mode. / shown when upstream_auth.type == 'static'

Scopes

Scope
gitlab:read
gitlab:write
gitlab:admin

Routes

Method	Pattern	Scope	Resource template
GET	/api/v4/users	gitlab:read	—
GET	/api/v4/projects	gitlab:read	—
GET	/api/v4/projects/{project_id}	gitlab:read	gitlab://projects/{{project_id}}
GET	/api/v4/projects/{project_id}/merge_requests	gitlab:read	gitlab://projects/{{project_id}}
POST	/api/v4/projects/{project_id}/merge_requests	gitlab:write	gitlab://projects/{{project_id}}
GET	/api/v4/projects/{project_id}/merge_requests/{merge_request_iid}/notes	gitlab:read	gitlab://projects/{{project_id}}/mr/{{merge_request_iid}}
POST	/api/v4/projects/{project_id}/merge_requests/{merge_request_iid}/notes	gitlab:write	gitlab://projects/{{project_id}}/mr/{{merge_request_iid}}
GET	/api/v4/projects/{project_id}/merge_requests/{merge_request_iid}	gitlab:read	gitlab://projects/{{project_id}}/mr/{{merge_request_iid}}
POST	/api/v4/projects/{project_id}/merge_requests/{merge_request_iid}/discussions	gitlab:write	gitlab://projects/{{project_id}}/mr/{{merge_request_iid}}
PUT	/api/v4/projects/{project_id}/merge_requests/{merge_request_iid}	gitlab:write	gitlab://projects/{{project_id}}/mr/{{merge_request_iid}}
POST	/api/v4/projects/{project_id}/access_tokens	gitlab:admin	gitlab://projects/{{project_id}}
GET	/api/v4/projects/{project_id}/registry/repositories	gitlab:read	gitlab://projects/{{project_id}}
GET	/api/v4/projects/{project_id}/registry/repositories/{repository_id}/tags	gitlab:read	gitlab://projects/{{project_id}}/registry/{{repository_id}}
GET	/api/v4/projects/{project_id}/registry/repositories/{repository_id}/tags/{tag_name}	gitlab:read	gitlab://projects/{{project_id}}/registry/{{repository_id}}
GET	/api/v4/projects/{project_id}/releases	gitlab:read	gitlab://projects/{{project_id}}
GET	/api/v4/projects/{project_id}/releases/{tag_name}	gitlab:read	gitlab://projects/{{project_id}}/releases/{{tag_name}}

MCP tools

Name	Scope	Description
list_users	gitlab:read	Look up GitLab users. Use username for an exact single-user lookup — this is how you resolve the numeric ids needed by assignee_ids/reviewer_ids on create_merge_request and edit_merge_request. search is a fuzzy fallback.
list_projects	gitlab:read	List GitLab projects visible to the caller. Narrow with membership/owned/starred/min_access_level rather than paging the whole instance; simple cuts the response to core fields.
get_project	gitlab:read	Get a GitLab project by ID or URL-encoded path.
list_merge_requests	gitlab:read	List merge requests for a project. Filter server-side rather than paging everything and discarding: scope covers the common 'mine' cases, and author/assignee/reviewer accept usernames so you don't need a list_users round-trip first.
create_merge_request	gitlab:write	Create a merge request. Set assignees, reviewers and labels here rather than opening bare and following up with edit_merge_request. Prefix the title with 'Draft:' to open it as a draft — GitLab derives draft status from the title.
list_merge_request_notes	gitlab:read	List comments on a merge request. Defaults to newest first; pass sort=asc to read a thread in the order it happened.
create_merge_request_note	gitlab:write	Add a comment on a merge request. WARNING: GitLab interprets leading slash commands in body as quick actions executed as the caller — a body of /merge, /approve, /assign @user or /close performs that action instead of commenting. Treat this argument as privileged input, not free text. GitLab's own created_at (backdating) and merge_request_diff_head_sha (arms the /merge quick action) attributes are deliberately not exposed by this connector.
get_merge_request	gitlab:read	Get a single merge request, including diff_refs (base_sha, head_sha, start_sha) — the SHAs needed to anchor an inline discussion comment to specific diff lines.
create_merge_request_discussion	gitlab:write	Start a discussion thread on a merge request. Supply position to anchor the comment to specific lines of the diff (an inline code-review comment); omit it for a plain MR-level thread. Position SHAs come from the merge request's diff_refs (fetch via get_merge_request).
edit_merge_request	gitlab:write	Update a merge request: title, description, state, assignees, reviewers, labels, target branch, milestone, and merge options. Only the fields you supply are changed.
create_project_access_token	gitlab:admin	Create a project access token. Least privilege is the caller's responsibility and GitLab's defaults are NOT least privilege: omitting access_level mints a Maintainer (40) token, and omitting expires_at gives it the maximum lifetime the instance allows. Always set both explicitly, and pick the narrowest scopes that work.
list_registry_repositories	gitlab:read	List container registry repositories for a project.
list_registry_tags	gitlab:read	List tags for a container registry repository.
get_registry_tag	gitlab:read	Get a container registry tag's details, including created_at (publish date), digest, and total size.
list_releases	gitlab:read	List releases for a project (newest first).
get_release	gitlab:read	Get a single release by tag name.