# Deploy from GitHub

> Connect a repository so a push to a branch builds and deploys the target that tracks it

URL: https://pier.run/docs/guides/deploy-from-github

**Goal.** A push to `main` in `acme`'s repository builds `api` on the platform and rolls
it, without a local docker.

### Apply first

Push-to-deploy resolves a branch to a target through the *applied* configuration, so the
targets must exist before a push can reach them:

```bash
pier apply
```

### Connect the repository

```bash
pier github connect
```

The command opens the browser to install Pier's GitHub App on the repository, or selects
a repository the App already has access to (`--repo owner/name` skips the picker). It then
asks which branch deploys which target, writes the answer to `pier.yaml` and applies it:

```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
```

`pier github status` shows the connection:

```bash
pier github status
```

```text title="output"
Account  Linked (@piercomputing)
Status   Not connected

```

### Push

Every push to `main` now runs a build on the platform from the commit, and rolls
`api/primary` when it succeeds. `pier deploys ls api` lists it with the commit and
author; `pier deploys logs <id>` streams the build.

A push that changes only `pier.yaml` is applied without a build. A push to a branch that
no target tracks does nothing, unless previews are enabled
([Preview deployments](/docs/guides/preview-deployments)).

## Behaviour

* **The push never reads `pier.yaml` from the repository.** Config changes are applied
  by `pier apply` from a checkout (or by a config-only push, once connected); the trigger
  table comes from what is applied.
* A connection can go **stale** (the App uninstalled, the repository moved). Pushes are
  then ignored, `pier github status` says so, and the connection heals when GitHub is
  reachable again; `pier github connect` repairs it now.
* `vcs.auto_deploy: false` keeps the connection but ignores pushes.
* `pier github set` changes which branch deploys which target; `pier github disconnect`
  removes the connection.

## See also

[GitHub](/docs/github) · [`pier github`](/docs/cli/reference/github) ·
[Builds](/docs/builds) · [Roll back a deploy](/docs/guides/roll-back-a-deploy)