Connect GitHub
What a GitHub connection gives you, what permissions each part needs, and what to do when one of them fails.
The full guide — the exact fine-grained permissions, the
connections.yml shapes for GitHub.com and GitHub Enterprise Server,
webhook setup, and a failure-by-failure section — lives with the code it
describes:
→ docs/CONNECT_GITHUB.md in archgraph-api
Kept there for the same reason as the on-premise runbook: every YAML example in it is parsed by the real loader in CI, the provider list is read from the capability registry, and the permission table is bound to the API calls the adapter actually makes. A stale line fails a test rather than an install. A copy on this site would have no such gate.
The short version
A GitHub connection does four separable things, and they need different permissions:
| Permission | Without it | |
|---|---|---|
| Clone private repositories | Contents: read | git clone fails |
| Push-triggered refresh | Webhooks: read and write | The poll refreshes instead — latency, not accuracy |
| Detect that upstream moved | Contents: read | Freshness fields stay unknown |
| The repository picker | Metadata: read | You paste URLs by hand |
Only the first is load-bearing. A token that can read contents and nothing else indexes every private repository correctly and keeps them current.
Which providers are supported
Four: GitHub, GitLab, Bitbucket and Azure DevOps. All four can answer "what is the current HEAD of this branch", which is the one capability that gates admission — without it a repository could be indexed once and then quietly go stale, and a connection that cannot be refreshed is refused rather than accepted into a state that looks healthy.
GitHub and GitLab have written guides — this page and Connect GitLab. Bitbucket and Azure DevOps work but are not yet written up, and they differ in one way worth knowing before you choose: neither can answer "what changed between these two commits", so every refresh re-extracts the whole repository rather than only the files that moved. Correct, but slower and more expensive per push.
A bare git URL with no hosting API needs no connection at all: it goes
straight into repos.yml.