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
stagd github connect
- The CLI opens GitHub’s install page for the Stagd HQ app.
- Pick your GitHub organization, then All repositories or the ones you want.
- 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:
stagd connections list
stagd connections delete <id>
One GitHub account can belong to one Stagd org at a time.