Troubleshooting and FAQ

Troubleshooting

No check appears on the pull request

  1. Is the repository enabled under Settings?
  2. Look at the webhook's delivery history. In Bitbucket, open the repository's Webhooks page. In GitHub, open Settings, Webhooks, the ArchGuard hook, then Recent Deliveries. A 401 means the signing secret differs: disable and enable the repository again. A connection or TLS error means WEBHOOK_PUBLIC_URL is not reachable over HTTPS from the internet. See Cloud deployment.
  3. Is the worker running (npm run worker)? Without it, events are accepted and wait in the queue.
  4. Check /api/health. Both db and redis should be up.

The check stays "in progress"

The worker may be stopped, or is retrying after an error. After the last retry (within about a minute) ArchGuard replaces it with a neutral, successful status. If it never changes, the worker is down.

Sign-in is refused

Your identity provider did not send a group that maps to a role. Ask your administrator to add you to one of the configured groups. See Roles and permissions.

"Not allowed"

The page needs a higher role. See the table in Roles and permissions.

Connecting Bitbucket fails

See the error table in Connect Bitbucket Cloud.

Enabling a repository fails

The token probably lacks the webhook permission (webhook on Bitbucket, Webhooks: Read and write on GitHub), or the repository is outside the token's access. Fix the token, paste it again and retry.

"Disable all … repositories before connecting …"

You are switching between Bitbucket and GitHub. Disable every repository of the current provider first. See Connect GitHub.

Approving an ADR fails

The token needs write access to repository contents: repository:write on Bitbucket, Contents: Read and write on GitHub. A GitHub branch rule that forbids direct pushes to the branch also blocks the commit. If the pull request was declined, the ADR cannot be committed. The draft stays pending after a failure.

A rule never fires

  • Check that it is enabled, and that its target patterns match the changed files.
  • The pull request must change at least one file matching the repository's structural triggers. Add domain paths for rules about ordinary source code. See Enable repositories.

A rule fires wrongly

Make the instruction more specific, narrow the target patterns, or set the severity to warning. See Guardrail rules.

FAQ

Does ArchGuard store our code? No. See Security and data handling.

Will it block our releases? Only if Bitbucket is configured to require the ArchGuard build, and only for blocking violations. See Pilot mode and shadow mode.

Which source-control systems are supported? Bitbucket Cloud and GitHub.com, one per organization. Bitbucket Data Center, GitHub Enterprise Server and GitHub Apps are not supported yet.

Can I host it in the cloud? Yes, on one Linux VM. See Cloud deployment.

Can I use my own model? Yes, any Bedrock model or OpenAI-compatible endpoint your company approves.

Why did my pull request get no ADR draft? Drafts are created only for new patterns, dependencies, schema changes or service contracts, and not when the pull request already contains an ADR file.

Does a new push create another comment? No. The existing comment is updated.

Who can approve ADRs? Architects and Admins. See Review and commit ADRs.