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

GitHub and GitLab. Both can answer "what is the current HEAD of this branch", which is what makes a repository refreshable without relying on webhook delivery.

Bitbucket and Azure DevOps have working adapters — they list, clone and register webhooks — but cannot answer that question, so a repository added through them would be indexed once and never updated. The connection is refused rather than accepted into a state that looks healthy and quietly goes stale.

A bare git URL with no hosting API needs no connection at all: it goes straight into repos.yml.