Getting started
ArchGuard reviews Bitbucket Cloud and GitHub.com pull requests that change your architecture: infrastructure code, database migrations, API contracts, dependency files and any domain paths you configure. It sets a build status on the commit, posts one comment on the pull request, and drafts an Architecture Decision Record (ADR) when the change deserves one.
How it works in one minute
- A pull request is opened or updated in an enabled repository.
- Bitbucket or GitHub sends a signed webhook. ArchGuard checks the signature and queues the work.
- A worker sets the ArchGuard build status to in progress, lists the changed files, and checks them against the repository's structural triggers.
- If nothing structural changed, the check turns green with "No architectural impact detected".
- Otherwise the worker sends only the relevant part of the diff to your approved language model, together with your guardrail rules.
- The result becomes a green or red build status and a pull request comment. If an ADR is needed, a draft waits in the dashboard for an Architect to approve.
Quickstart checklist
- Follow Local setup to run it on your machine, or Cloud deployment to host it on a cloud VM with HTTPS.
- Sign in with your company single sign-on. See Roles and permissions for the groups you need.
- As an Admin, open Settings and connect Bitbucket Cloud or GitHub.
- Enable a repository.
- Open a pull request that changes a Terraform file or
package.json. - Watch the ArchGuard check appear on the pull request, and read the comment.
Start in shadow mode: do not make the ArchGuard check required for the first week, so nobody is blocked while you tune the rules.
Where to go next
- Understand the results: Build statuses and comments
- Tune what gets flagged: Guardrail rules
- Something not working: Troubleshooting and FAQ