> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# GitHub integration

> Connect a GitHub repository so every push becomes a deployment.

Connect a GitHub repository to an <Tooltip tip="A Compute app: a deployable service inside a project. Not 'your application' in general.">app</Tooltip> and every push becomes a deployment. You install the Unkey GitHub App once, connect a repository, and push.

## Install the GitHub App

You install the Unkey GitHub App once per workspace, on a GitHub organization or personal account, and choose which repositories it can see.

1. Start from any of these places in the dashboard: the **Import from GitHub** step when you create an app, the **GitHub** card in an app's settings, or [workspace settings](/docs/platform/workspace/settings).
2. Approve the installation on GitHub. GitHub sends you back to Unkey.

To do it with the API, call `github.installApp` with a root key that has `workspace.*.install_github`, and open the URL it returns.

You can install the app on more than one GitHub account. An installation belongs to one workspace only, so a second workspace can't use it.

## Connect a repository to an app

Pick the repository when you create the app, or later in the app's settings. From the CLI, pass `--git` to [create-app](/docs/compute/cli/apps/create-app) or [update-app](/docs/compute/cli/apps/update-app).

You connect a repository per app, not per project. In a monorepo, two apps can connect to the same repository and use different build settings.

The app's default branch deploys to production. It starts as the repository's default branch on GitHub, and you can change it with `apps.updateApp`.

To stop deploying from pushes, click **Disconnect repository** in the app's settings. The dashboard warns that "Deployments will no longer be triggered by pushes to this repository." Existing deployments keep running.

## What deploys when you push

Two things on GitHub create a deployment:

* **A push to a branch.** The first push of a new branch counts, which is how a branch gets its first preview. Pushing a tag or deleting a branch doesn't deploy.
* **A pull request from a fork**, when it's opened or gets new commits. Pull requests from branches in your own repository don't deploy again, because the push already did.

The branch picks the <Tooltip tip="A production or preview environment of a Compute app, not the dashboard label on a key.">environment</Tooltip>. The app's default branch (or `main` if none is set) deploys to production. Every other branch, and every fork pull request, deploys to preview. If several apps are connected to the repository, one push creates one deployment per app.

## Skip deploys with auto deploy and watch paths

Two [build settings](/docs/compute/configure/build-settings) can stop a push from deploying. We check them in this order:

1. **Auto deploy off.** The push is recorded as `skipped` with "Auto deploy is disabled for this environment." Watch paths aren't checked.
2. **Watch paths set, and no changed file matches.** The push is skipped with "Watch paths did not match any changed files." If a pattern isn't a valid glob, it's skipped with a message naming the pattern.

Otherwise, we create a deployment. Watch paths also apply to fork pull requests.

Patterns use `**` globbing. `src/**` matches everything under `src`, `**/*.go` matches every Go file, and a pattern with no wildcard matches only that exact path.

## Approve pull requests from forks

A fork pull request runs code from someone without write access to your repository, with your environment variables. So we never build it automatically.

1. The deployment waits in `awaiting_approval`. On the pull request, a failing check named **Unkey Deploy Authorization** says "Awaiting authorization from a project member" and links to the deployment.
2. A project member approves it in the dashboard. The build starts.

Pushes from people with write access to the repository don't need approval.

Fork previews get their own hostname prefix, `<project>[-<app>]-fork-<fork owner>-...`, so you can't confuse them with your own branches. You can also deploy a fork yourself from the **Create Deployment** dialog, or with `deployments.createDeployment` by passing `git.repository` as `owner/repo` and a `commitSha`.

## What you'll see on GitHub

Each deployment of a connected app reports back to GitHub:

* **A GitHub Deployment** on the commit, labeled `project - env` (or `project/app - env` when the app isn't `default`), linking to the environment's `unkey.app` domain. Its status goes from "Deployment queued" to "Deploying to regions...", "Configuring routing...", and "Deployment is live", or to a failure that names the step that failed.
* **A pull request comment**, when the branch has an open pull request or the deployment came from a fork. We keep one comment per pull request up to date, with a row per app and environment: status, a **Visit Preview** link, an **Inspect** link to the dashboard, and when it last changed.
* **A commit status**, only for fork deployments waiting for approval.

## Troubleshooting: a push didn't deploy

Check these in order:

1. The Unkey GitHub App is installed on the account that owns the repository, and has access to it.
2. The repository is connected to the app in its settings.
3. Auto deploy is on for the environment the branch maps to.
4. The push changed a file that matches the watch paths, if any are set.
5. The app's deployments list shows a `skipped` or `failed` row with the reason.

## Next steps

<Columns cols={2}>
  <Card title="Build settings" icon="sliders" href="/docs/compute/configure/build-settings">
    Root directory, Dockerfile, build command, watch paths, auto deploy.
  </Card>

  <Card title="Production and preview" icon="code-branch" href="/docs/compute/concepts/production-and-preview">
    What happens after a deployment on either branch kind reaches ready.
  </Card>
</Columns>