> 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/github.md).

# GitHub MCP server

Install the GitHub App integration and its MCP server so agents behind the P0 AI Gateway can request scoped access to your GitHub repositories.

The **GitHub App** integration lets agents behind the P0 AI Gateway (see [P0 Runtime Access for AI](https://docs.p0.dev/readme/agentic-control-plane.md)) request permissions on one repository in your GitHub organization, such as `contents:read` or `pull_requests:write`. For each grant, P0's connector mints a GitHub App installation token that covers only that repository and the approved permissions, and stores it in your Google Secret Manager. The gateway calls GitHub's hosted MCP server with that token.

This integration is for agents. To give people just-in-time access, use [GitHub](https://docs.p0.dev/integrations/resource-integrations/github.md) for repository roles and team membership.

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

Setup has four parts, in this order:

1. Install the GitHub organization in P0, which deploys P0's connector in a Google Cloud project.
2. Create and install a GitHub App, and give P0 its key.
3. Add the GitHub MCP server to your gateway.
4. Write the policies that decide which agents get which permissions.

## 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://api.githubcopilot.com` and Google Secret Manager.
* 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, and permission to apply Terraform in that project.
* [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 GitHub organization owner, who can create and install GitHub Apps for the organization.

## Install the organization in P0

1. Navigate to **Integrations** on [p0.app](https://p0.app), select **GitHub App**, and choose the **Credential provisioning** component.
2. Click **Add Organization**, and enter the organization's GitHub login, such as `acme` for `github.com/acme`. Agents and policies use this name for the organization.
3. For **Secret manager provider**, choose **Google Secret Manager**, then the **Installation** for the project where the connector will run. Click **Next**.
4. P0 generates a Terraform configuration. Copy it into your Terraform project, `apply` it, then click **Next**.

   The configuration creates:

   * A Cloud Run service, `p0-connector-github-ai`, that runs P0's connector under its own service account, `p0-github`.
   * A secret for the GitHub App's private key, `p0_install_github_<organization>_private-key-pem`, 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_github_<organization>_`, 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 Cloud Run service can take a minute to start. If the check fails, wait a minute and click **Next** again.

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

## Create and install the GitHub App

1. **Create the app.** Click **Create access app**. GitHub opens a new app form for your organization, filled in by P0, with the name `P0 <organization> machine access`. GitHub limits app names to 34 characters, so shorten the name if GitHub rejects it.

   The app starts with read permissions only, plus write on workflows. A token can hold no permission that the app lacks. To let agents request more, raise the app's permissions on its settings page, either now or later. Once the app is installed, an organization owner must also approve each new permission on the installation before tokens can hold it.
2. **Install the app** on your organization from the app's settings page, under **Install App**. Choose the repositories agents may reach. Agents can only see and request repositories that the installation covers.
3. **Store the private key.** On the app's settings page, generate a private key, save the downloaded file as `private-key.pem`, and run the command P0 shows:

   ```bash
   gcloud secrets versions add p0_install_github_<organization>_private-key-pem \
     --project=<project-id> --data-file=private-key.pem
   ```

   P0 never sees the key: only your connector reads it. Delete the downloaded file once it is stored.
4. **Enter the GitHub App ID**, shown on the app's settings page, in P0.
5. Review the summary and click **Finish**. The organization now appears with the state **Installed**.

## Add the GitHub MCP server

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 **GitHub**.
2. The server now appears with the state **Installed**.

One GitHub MCP server serves every organization you install. Each grant names the organization it is for.

## How agents request access

An agent requests access with the server's `access` tool. It names the organization by its GitHub login, one repository by its name without the organization, such as `api`, and one or more permissions as `<permission>:<level>`. The agent's `list` tool shows the installed organizations, the repositories the app can reach, and the permissions it can request.

These permissions can be requested at `read` or `write`:

`actions`, `administration`, `artifact_metadata`, `attestations`, `checks`, `code_quality`, `codespaces`, `contents`, `dependabot_secrets`, `deployments`, `discussions`, `environments`, `issues`, `merge_queues`, `metadata`, `packages`, `pages`, `pull_requests`, `repository_custom_properties`, `repository_hooks`, `secret_scanning_alerts`, `secrets`, `security_events`, `single_file`, `statuses`, and `vulnerability_alerts`.

`repository_projects` can also be requested at `admin`, and `workflows` only at `write`.

Once a request is approved, access usually works within 15 to 45 seconds, and can take up to two minutes. A request fails if the app lacks a requested permission or can't reach the repository. The error names the repository and permissions, so you can add them to the app or its installation.

Each agent has one token per repository. A new grant on the same repository adds its permissions to that token, and when a grant ends, P0 removes its permissions.

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

{% hint style="info" %}
When access ends, P0 deletes the secret that holds the token, so the gateway can no longer use it. GitHub can't revoke a single installation token, so a token that was already issued stays valid until it expires, one hour after it was issued.
{% endhint %}

## Write policies for GitHub

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

* `organization`: the organization, keyed on `name`, its GitHub login.
* `repository`: the repository, keyed on `name`, its full name, such as `acme/api`.
* `policy`: the permission, keyed on `name`, such as `contents:read`. A rule covers a request only if it matches every permission in it.

Patterns are regular expressions, so a rule can match one permission (`^contents:write$`), every level of one permission (`^contents:.*$`), or every read permission (`^.*:read$`).

For example, auto-approve reading code and writing pull requests for one agent, but only on `acme/api`:

```yaml
- requestor:
    type: agentic
    actor:
      type: agent-client
      clientId: release-agent
    subject:
      type: any
  resource:
    type: integration
    service: github-ai
    accessType: permission
    filters:
      organization:
        effect: keep
        key: name
        pattern: ^acme$
      repository:
        effect: keep
        key: name
        pattern: ^acme/api$
      policy:
        effect: keep
        key: name
        pattern: ^(metadata:read|contents:read|pull_requests:(read|write))$
  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 GitHub access.
