> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/agentic-access/agentic-gateway/mcp-server/gitlab.md).

# GitLab MCP server

Install the GitLab agentic integration and its MCP server so agents behind the P0 AI Gateway can request roles on projects in your GitLab.com group.

The **GitLab** agentic integration lets agents behind the AI Gateway, part of [P0 Runtime Access for AI](https://docs.p0.dev/readme/agentic-control-plane.md), request a role on projects in your GitLab.com top-level group, such as Reporter on `acme/app`. For each agent, P0's connector creates a GitLab service account in your group, makes it a member of the approved projects with the approved role, and stores its token in your secret manager. The gateway calls GitLab's hosted MCP server with that token. When access ends, P0 deletes the service account, and its token stops working at once.

{% hint style="info" %}
The GitLab agentic integration is in beta. Functionality and configuration may change.
{% endhint %}

Setup has four parts, in this order:

1. Install the GitLab group in P0, which deploys P0's connector in AWS or Google Cloud.
2. Create an admin service account in GitLab and give P0 its token.
3. Add the GitLab MCP server to your gateway.
4. Write the policies that decide which agents get which roles.

## Prerequisites

* A registered [Gateway](https://docs.p0.dev/agentic-access/agentic-gateway/gateway.md) component, with the gateway deployed in your environment. The gateway must be able to reach `https://gitlab.com` and your secret manager.
* One of these, with permission to apply Terraform where it's installed. P0's connector runs there, and grant tokens are stored there.
  * On AWS:
    * The [AWS Secrets Manager](https://docs.p0.dev/integrations/resource-integrations/aws-secrets-manager.md) integration installed on an AWS account. The connector runs there on AWS Lambda. Applying its Terraform also needs Docker and the AWS CLI, signed in to that account, to copy P0's connector image into your Amazon ECR.
    * [AWS OIDC](https://docs.p0.dev/agentic-access/credential-sources/aws-oidc.md) installed for that same account. The gateway uses it to read each grant's token.
  * On Google Cloud:
    * The [Google Cloud](https://docs.p0.dev/integrations/resource-integrations/google-cloud.md) integration installed for your Google Cloud organization.
    * The [Google Secret Manager](https://docs.p0.dev/integrations/resource-integrations/google-secret-manager.md) integration installed on the Google Cloud project where the connector will run. The connector runs there on Cloud Run.
    * [GCP Workload Identity Federation](https://docs.p0.dev/agentic-access/credential-sources/gcp-wif.md) installed for that same project. The gateway uses it to read each grant's token.
* A GitLab.com top-level group, and an Owner of that group who has verified their identity with GitLab. GitLab lets only such an Owner create service accounts.
* The MCP server allowed for the group. This is on by default. In GitLab, check **Settings** > **General** > **Permissions and group features** > **MCP client access** > **Allow connection to GitLab**.

## Install the group in P0

1. Navigate to **Integrations** on [p0.app](https://p0.app), select **GitLab**, and choose the **Credential provisioning** component.
2. Click **Add Group**, and enter an identifier for it, such as `acme`. Agents and policies use this name for the group. Use letters, digits, and hyphens.
3. For **Secret manager provider**, choose where the connector will run:

   * **AWS Secrets Manager**: choose the installation for the AWS account, and enter the region that stores the secrets.
   * **Google Secret Manager**: choose the installation for the project.

   Click **Next**.
4. P0 generates a Terraform configuration. Copy it into your Terraform project, `apply` it, then click **Next**.

   On AWS, the configuration creates:

   * An Amazon ECR repository with a copy of P0's connector image, and a Lambda function, `p0-connector-gitlab-ai-aws`, that runs it with its own IAM role.
   * A secret for the GitLab admin token, `p0/install/gitlab/<identifier>/admin-token`, which only the connector can read.
   * Permission for the connector to create and manage the secrets that hold grant tokens. Their names start with `p0/access-token/gitlab/<identifier>/`, and the connector can touch no other secret.
   * A policy on P0's IAM role in the account that lets P0 invoke the function.

   On Google Cloud, it creates:

   * A Cloud Run service, `p0-connector-gitlab-ai`, that runs P0's connector under its own service account, `p0-gitlab`.
   * A secret for the GitLab admin token, `p0_install_gitlab_<identifier>_admin-token`, which only the connector can read.
   * Permission for the connector to create and manage the secrets that hold grant tokens. Their names start with `p0_access-token_gitlab_<identifier>_`, and the connector can touch no other secret.
   * Bindings that let P0's Google Cloud service account call the connector and read its URL. The connector accepts calls from that service account only.
   * The Cloud Run, Secret Manager, IAM, and Resource Manager APIs, turned on in the project.

   When you click **Next**, P0 checks that the connector is deployed. A new connector can take a minute to start. If the check fails, wait a minute and click **Next** again.

{% hint style="warning" %}
Install each GitLab group in its own AWS account or Google Cloud project. The Terraform for a second group in the same account or project conflicts with the first.
{% endhint %}

## Set up GitLab

1. **Create an admin service account** for P0. In your top-level group, go to **Settings** > **Service accounts** and add a service account. P0 uses it only to create and delete the service accounts of grants.
2. **Make it an Owner** of the top-level group under **Manage** > **Members**. Only an Owner can manage the group's service accounts.
3. **Store its token.** Create a personal access token for the admin service account with the `api` scope. Set `GITLAB_TOKEN` to it, and run the command P0 shows. On AWS:

   ```bash
   printf '%s' "$GITLAB_TOKEN" | \
     aws secretsmanager put-secret-value \
     --secret-id p0/install/gitlab/<identifier>/admin-token \
     --region <secrets-region> --secret-string file:///dev/stdin
   ```

   On Google Cloud:

   ```bash
   printf '%s' "$GITLAB_TOKEN" | \
     gcloud secrets versions add p0_install_gitlab_<identifier>_admin-token \
     --project=<project-id> --data-file=-
   ```

   P0 never sees the token: only your connector reads it. The connector cannot grant access until the secret holds the token. When the token expires, create a new one and store it the same way.
4. **Enter the Group ID** in P0. It is the number on the group's overview page in GitLab.
5. Review the summary and click **Finish**. The group now appears with the state **Installed**.

## Add the GitLab MCP server

You can add the GitLab MCP server once at least one group is installed.

1. Follow the shared steps in [MCP server](https://docs.p0.dev/agentic-access/agentic-gateway/mcp-server.md#add-an-mcp-server) to name the server and choose its gateway. On the configuration screen, set the following fields, then click **Finish**:
   * **Credential source**: choose **Vaulted credential**.
   * **Definition**: choose **P0**, then select **GitLab**.
2. The server now appears with the state **Installed**.

One GitLab MCP server serves every group you install. Each grant names the group it is for.

## How agents request access

An agent requests access with the server's `access` tool. It names the group by its P0 identifier, and one or more projects, each with a role, in the form `<project path>:<role>`, such as `acme/app:reporter`. The role is one of `guest`, `reporter`, `developer`, or `maintainer`. The agent's `list` tool shows the installed groups and every project in them, with each role.

Once a request is approved, access usually works within 15 seconds. Agents see every GitLab tool whether or not their roles cover it. GitLab refuses a call on a project the agent is not a member of, or that its role does not allow.

Each agent has one service account per group, named `p0-grant-` followed by a hash, and shown in the group's service accounts as **P0 grant**. A new grant in the same group adds its projects to that service account. If two grants name the same project, the higher role applies. When a grant ends, P0 removes its projects, and when the agent's last grant in the group ends, P0 deletes the service account. Changes apply to the agent's next call, including in an open MCP session.

{% hint style="info" %}
On GitLab's Free tier, a top-level group holds at most 100 service accounts, including the admin service account. Agents with access in the group count toward that limit.
{% endhint %}

See [Requesting access](https://docs.p0.dev/agentic-access/using-the-gateway/requesting-access.md) for how agents submit and use requests.

## Write policies for GitLab

Match GitLab requests in an agentic access policy ([Agentic access policies](https://docs.p0.dev/agentic-access/agentic-access-policies.md)) with `service: gitlab-ai` and `accessType: permission`. Two filters narrow them:

* `group`: the group, keyed on `name`, the identifier you gave the group in P0.
* `policy`: the project and role, keyed on `name`, in the form `<project path>:<role>`. A rule covers a request only if it matches every project in it.

Patterns are regular expressions, so a rule can match one project and role (`^acme/app:reporter$`), every role on one project (`^acme/app:.*$`), or one role on every project (`^.*:reporter$`).

For example, auto-approve Reporter on any project for one agent, but only in the `acme` group:

```yaml
- requestor:
    type: agentic
    actor:
      type: agent-client
      clientId: review-agent
    subject:
      type: any
  resource:
    type: integration
    service: gitlab-ai
    accessType: permission
    filters:
      group:
        effect: keep
        key: name
        pattern: ^acme$
      policy:
        effect: keep
        key: name
        pattern: ^.*:reporter$
  approval:
    - type: persistent
```

## Next steps

* Define the [Agentic access policies](https://docs.p0.dev/agentic-access/agentic-access-policies.md) that determine which agents and users may request GitLab access.
