# GitHub

> The connection between a project and a repository — installation, triggers, what a push does, and how a connection heals

URL: https://pier.run/docs/github

A project connects to one repository through Pier's GitHub App. Once connected, a push to
a branch that a target tracks builds and deploys that target on the platform.

```yaml title="pier.yaml"
vcs:
  provider: github
  repo: acme-inc/acme
  auto_deploy: true
environments:
  prod:
    apps:
      - name: api
        build_context: ./api
        targets:
          - name: primary
            deploy: { branch: main }
          - name: canary
            deploy: { branch: develop }
```

## What a push does

1. GitHub delivers the push to Pier.
2. Pier looks up which targets track the branch in the **applied** configuration, not in
   the repository's `pier.yaml`.
3. For each, a build runs from the commit (Dockerfile or detected strategy) and, on
   success, the target rolls. Sites are built and published the same way.
4. `pier deploys ls` shows the row with commit, author and message.

Pushes to branches no target tracks are ignored, unless the app or site has a `previews`
policy ([Preview deployments](/docs/guides/preview-deployments)). A push that changes only
`pier.yaml` is applied without a build.

## Connection state

| State                | Means                                                                                                                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connected`          | pushes deploy                                                                                                                                                                                |
| `stale`              | the App can no longer see the repository (uninstalled, moved, permissions changed); pushes are ignored. Heals by itself when GitHub is reachable again; `pier github connect` repairs it now |
| `auto_deploy: false` | connected, pushes ignored on purpose                                                                                                                                                         |

`pier github status` shows the state and the triggers.

## Commands

| Command                                   | Does                                                                                                |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `pier github connect [--repo owner/name]` | install the App, pick the repository and triggers, write `vcs:` and `deploy:` to `pier.yaml`, apply |
| `pier github set`                         | change which branch deploys which target                                                            |
| `pier github status`                      | connection, triggers, last delivery                                                                 |
| `pier github disconnect`                  | remove the connection; the targets stay                                                             |

## See also

[Deploy from GitHub](/docs/guides/deploy-from-github) · [Builds](/docs/builds) · [`pier github`](/docs/cli/reference/github)