# Connect GitHub

> Install the Stagd GitHub App on your GitHub organization and choose which repositories get previews.

Stagd works through a GitHub App, **Stagd HQ** on GitHub. You choose the repositories it can see, and it only asks for what previews need.

## Connect

```sh
stagd github connect
```

1. The CLI opens GitHub's install page for the Stagd HQ app.
2. Pick your GitHub organization, then **All repositories** or the ones you want.
3. Click **Install & Authorize**.

GitHub sends you back to Stagd, which links the installation to your org. The CLI finishes on its own and `stagd repos list` shows what Stagd can see.

> **Why authorize?** Installation ids on GitHub are easy to guess. Stagd only links an installation that you, the person who came back, can see in your own GitHub account.

## What the app asks for

| Permission | Access | Used for |
|---|---|---|
| Contents | Read | Building your code |
| Metadata | Read | Listing repositories |
| Pull requests | Write | Knowing which branch and commit to preview, the one comment Stagd keeps up to date on each PR, and the preview label (`previews: { label: … }`) |
| Checks | Write | The preview's status on the PR, and the checks a preview waits for (`wait:`) |
| Actions | Read | The workflow runs a preview waits for, e.g. the one that pushes its images |
| Deployments | Write | The preview link in GitHub's deployments |

It listens for these events: pull requests (opened, pushed to, labelled, closed), comments on them (the `/stagd` commands), and finished check runs and workflow runs.

## Change or disconnect

- To add or remove repositories, change the installation on GitHub, under your organization's **Settings → GitHub Apps → Stagd HQ → Configure**.
- To disconnect a GitHub account from your Stagd org:

```sh
stagd connections list
stagd connections delete <id>
```

One GitHub account can belong to one Stagd org at a time.
