Connect GitHub
ArchGuard supports GitHub.com with a fine-grained personal access token. GitHub Enterprise Server and GitHub Apps are not supported yet. Only users with the Admin role can connect.
An organization uses one source-control provider at a time: Bitbucket Cloud or GitHub. See Switching from Bitbucket.
Create a fine-grained personal access token
- In GitHub, open Settings, then Developer settings, Personal access tokens, Fine-grained tokens, and select Generate new token.
- Resource owner: your user account, or the organization that owns the repositories. Organizations can require an owner to approve fine-grained tokens before they work.
- Expiration: pick a date and put a reminder in your calendar. When the token expires, evaluations stop (pull requests get a neutral result).
- Repository access: choose Only select repositories and pick the test repositories. ArchGuard only sees what you select here.
- Under Repository permissions, set:
| Permission | Access | Why ArchGuard needs it |
|---|---|---|
| Metadata | Read (set automatically) | List repositories and read repository details. |
| Contents | Read and write | Read the ADR folder, and commit approved ADR files. |
| Pull requests | Read and write | Read pull requests and changed files, and post the summary comment. |
| Commit statuses | Read and write | Set the ArchGuard check on each commit. |
| Webhooks | Read and write | Register and remove the pull request webhook. |
- Select Generate token and copy it. GitHub shows it once.
These permissions match GitHub's published list of the permissions each REST endpoint needs. They have not been tried against a live account in this build.
Connect
- Open Settings in ArchGuard.
- Choose GitHub.com as the provider.
- Enter the owner: the user or organization name in your repository URLs (
github.com/<owner>/...). It must be the token's resource owner. - Paste the token and select Validate and connect.
ArchGuard checks the token, stores it encrypted (AES-256-GCM) and lists the owner's repositories that the token can see. Archived repositories are skipped.
Enable repositories
Select Enable next to a repository. ArchGuard creates a repository webhook for Pull requests events, signed with a new random secret, pointing at <your address>/api/webhooks/github. GitHub immediately sends a ping delivery, which ArchGuard accepts and ignores.
The address comes from WEBHOOK_PUBLIC_URL, which GitHub must be able to reach over HTTPS. See Cloud deployment.
ArchGuard evaluates a pull request when it is opened, reopened, marked ready for review, or gets new commits. Edits to the title, labels or reviewers do not trigger an evaluation.
What you will see on a pull request
- A status named ArchGuard in the checks list, which shows pending, then success or failure. Its Details link opens the ArchGuard dashboard.
- One comment with the results, updated on every run. The comment and any ADR commit appear under the name of the account that owns the token. For a team pilot, consider a dedicated machine account.
The meanings are the same as for Bitbucket. See Build statuses and PR comments.
Require the check before merging
Leave this off for the first week (shadow mode). When you are ready:
- In the repository, open Settings, then Rules (rulesets) or Branches (branch protection).
- Add a rule for your main branch with Require status checks to pass.
- Search for and add ArchGuard. It appears in the list after ArchGuard has run once on that repository.
Neutral results are reported as success, so a very large pull request or a model outage never blocks a merge.
Limits
GitHub refuses to return a diff for pull requests over 300 files or 20,000 lines. ArchGuard then reports a neutral "too large to evaluate" result and asks for a manual review.
Switching from Bitbucket
- Under Settings, Disable every Bitbucket repository. ArchGuard refuses to switch while any repository is enabled, so no webhook is left behind.
- Connect GitHub as above.
History from the Bitbucket repositories stays on the dashboard. Those repositories are no longer listed under Settings.
Errors you may see
| Message | Meaning |
|---|---|
| The access token was rejected (401) | Wrong, expired or revoked token. |
| Owner not found (404) | Check the owner name, and that the token's resource owner is that account or organization. |
| The token is not allowed to read this owner (403) | The organization has not approved the token, or it belongs to another owner. |
| Could not change the repository | The token lacks the Webhooks permission, or the repository is not in the token's selected repositories. |
| Commit failed | The token lacks Contents: Read and write, or a branch rule blocks direct commits to that branch. |
| Disable all Bitbucket Cloud repositories before connecting GitHub | See Switching from Bitbucket. |
More help: Troubleshooting and FAQ.