# GitHub

Connecting a GitHub repository wires a project to your repo. Deploys run in your own GitHub Actions, through [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action); the connection provides two things around them:

- **Credentials.** Workflow runs in the connected repository exchange their GitHub OIDC token for a short-lived Prisma workspace token, so the deploy workflow needs no secrets.
- **Branch lifecycle.** Branch events keep the matching platform branches in sync, including tearing a preview down when its Git branch is deleted.

For the full setup, from connection to a live preview per branch, follow [Deploy on push](/guides/integrations-deploy-on-push).

## [How it works](#how-it-works)

The connection has two levels:

How deploy on push works: a GitHub connection plus a deploy workflowStep 1 of 3

The connection has two levels. First, your workspace installs the Prisma GitHub App once. That installation is what lets Prisma see your repositories.

The workspace owns the GitHub App installation; each project points at a single repository. Once connected, Prisma verifies the repository identity behind each credential exchange and listens for the repo's branch events.

## [Connect a repo](#connect-a-repo)

You can connect through the [Console](https://pris.ly/pdp) or from the CLI. The Console also opens a pull request that adds the deploy workflow to the repository. The CLI sets up the connection only, and you [add the workflow yourself](/guides/integrations-deploy-on-push#4-add-the-deploy-workflow).

From a linked project directory, connect your Git origin:

:::code-group
```title="bun"
bunx prisma git connect
```

```bash title="pnpm"
pnpm prisma git connect
```

```bash title="yarn"
yarn prisma git connect
```

```bash title="npm"
npx prisma git connect
```
:::

To name the repository explicitly:

::::tabs
:::tab{title="bun"}
```
bunx prisma git connect https://github.com/acme/shop
```
:::

:::tab{title="pnpm"}
```bash
pnpm prisma git connect https://github.com/acme/shop
```
:::

:::tab{title="yarn"}
```bash
yarn prisma git connect https://github.com/acme/shop
```
:::

:::tab{title="npm"}
```bash
npx prisma git connect https://github.com/acme/shop
```

If the GitHub App isn't installed yet, the CLI opens the browser to finish the install. The command needs an interactive terminal: it waits for the install to complete, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED`. For headless setups, connect through the Console instead.

Disconnect when you're done:
:::
::::

If the GitHub App isn't installed yet, the CLI opens the browser to finish the install. The command needs an interactive terminal: it waits for the install to complete, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED`. For headless setups, connect through the Console instead.

Disconnect when you're done:

::::tabs
:::tab{title="bun"}
```
bunx prisma git disconnect
```
:::

:::tab{title="pnpm"}
```bash
pnpm prisma git disconnect
```
:::

:::tab{title="yarn"}
```bash
yarn prisma git disconnect
```
:::

:::tab{title="npm"}
```bash
npx prisma git disconnect
```

Disconnecting stops the credential exchange and the branch automation. It doesn't delete the project or tear down existing branches.
:::
::::

Disconnecting stops the credential exchange and the branch automation. It doesn't delete the project or tear down existing branches.

## [What the connection does](#what-the-connection-does)

Once a project is connected:

- **Actions runs can authenticate.** A workflow job with `id-token: write` gets a workspace token through the OIDC exchange. The token is valid for 30 minutes and is only issued for the connected repository; unconnected repositories and forks are refused, and the deploy action then skips with a green run.
- **Branch created** → creates the matching platform branch.
- **Branch deleted** → tears down the matching platform branch and its resources. Your production and default branches are exempt from this cleanup.

Pushes are not handled by the platform. Your repository's own workflow deploys them, so a connected repo without a deploy workflow deploys nothing. Connecting also doesn't create branches retroactively: it aligns your default branch with the repo's default branch and wires up automation for future events.

## [What's not supported](#whats-not-supported)

GitHub is the only supported provider; others return `REPO_PROVIDER_UNSUPPORTED`. Pull-request comments and preview comments aren't currently supported.

## [Next steps](#next-steps)

- [Deploy on push](/guides/integrations-deploy-on-push): the full walkthrough, from connection to per-branch previews.
- [Branching](/guides/features-2-compute-branching): how platform branches map to Git.
- [Environment variables](/guides/features-2-compute-environment-variables): per-branch config for previews.

## Related pages

- [Authentication & Tools](./authentication-tools-index.md)
- [Build](./build-index.md)
- [Changelog](../changelog.md)
- [Concepts](./concepts-index.md)
- [Console commands](./console-commands-index.md)
- [Contract Authoring](./contract-authoring-index.md)
- [Core Concepts](./core-concepts-index.md)
- [Data Modeling](./data-modeling-index.md)
- [Database](./database-index.md)
- [DB commands](./db-commands-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.