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

  1. A pull request is opened or updated in an enabled repository.
  2. Bitbucket or GitHub sends a signed webhook. ArchGuard checks the signature and queues the work.
  3. A worker sets the ArchGuard build status to in progress, lists the changed files, and checks them against the repository's structural triggers.
  4. If nothing structural changed, the check turns green with "No architectural impact detected".
  5. Otherwise the worker sends only the relevant part of the diff to your approved language model, together with your guardrail rules.
  6. 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

  1. Follow Local setup to run it on your machine, or Cloud deployment to host it on a cloud VM with HTTPS.
  2. Sign in with your company single sign-on. See Roles and permissions for the groups you need.
  3. As an Admin, open Settings and connect Bitbucket Cloud or GitHub.
  4. Enable a repository.
  5. Open a pull request that changes a Terraform file or package.json.
  6. 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