Bootstrap your first repo

The fastest way to onboard a repo to ArchRails is to commit a single empty file and let the platform generate the first draft of your architecture for you. You review the result in a normal PR, edit anything that doesn't match reality, and merge. That's it — no out-of-band setup, no separate dashboard wizard.

What bootstrap actually does

Bootstrap reads the CALM document(s) you already have in your repo and produces a first draft of .archrails/config.yml — the small file that tells ArchRails which CALM files describe your architecture, which branches are governed, and which code paths map to which CALM nodes.

Bootstrap scans your whole repo for *.calm.json files, with a scoring boost for conventional locations (architecture/, arch/, topology/, system/, files named calm.json or architecture.json). Keep yours wherever fits your codebase. For each CALM node, bootstrap infers a likely mapping path from your directory layout; anything it can't pin down is marked REVIEW REQUIRED so it's obvious in the PR review.

Step 1 · Commit an empty config

On a new branch, create the directory and an empty file:

git checkout -b archrails/bootstrap
mkdir -p .archrails
touch .archrails/config.yml
git add .archrails/config.yml
git commit -m "chore: bootstrap ArchRails"
git push -u origin archrails/bootstrap

The file is genuinely empty — zero bytes. That empty file is the signal: “ArchRails, fill this in for me.”

Step 2 · Open the PR

Open a pull request against your default branch (or whichever branch you want bootstrap to target). Title and body are up to you; a typical first PR looks like:

Title:  chore: bootstrap ArchRails
Body:   Empty .archrails/config.yml so ArchRails generates the
        initial architecture from this repo.

The moment that PR is open, ArchRails runs — you'll see a check appear within seconds.

Step 3 · Review the generated config

A minute or two later, a follow-up commit from github-actions[bot] will appear on your branch:

chore: regenerate .archrails/config.yml via ArchRails bootstrap

That commit adds the populated .archrails/config.yml. Your existing *.calm.json files are untouched — bootstrap reads them to derive the config but never writes to them. A small example of the generated config for a Java service might look like:

# .archrails/config.yml — generated by ArchRails
# Paths were inferred from your repo structure.
# Adjust any path marked REVIEW REQUIRED before merging.

version: 1

governance:
  governed_branches:
    - main

  sources:
    - id: architecture
      provider: calm
      file: "architecture/system.calm.json"

mapping:
  # confidence: high
  - path: "customer-portal"
    node: customer-portal

  # confidence: high
  - path: "orders-server"
    node: orders-server

  # ⚠ REVIEW REQUIRED — no code directory matched for 'orders-db' (type: database).
  # Likely infrastructure-only or external — uncomment and set a path if this
  # node represents code in this repo.
  # - path: ""
  #   node: orders-db

integrations:
  github:
    app: archrails

Three things to notice:

• governance.governed_branches defaults to your tenant's default branch list. Only PRs landing on a governed branch get architecture review — experimental branches stay out of the way.
• Each mapping entry binds a path to a node. The node: value is the unique-id from your CALM file. Bootstrap picks a path-aligned slug (customer-portal ↔ customer-portal/) so the binding is obvious; keep that convention when you add nodes by hand.
• Anything ArchRails couldn't confidently match to a directory is left as a commented-out REVIEW REQUIRED block. The database node above, for instance, is referenced by other nodes but doesn't have a corresponding folder — a human needs to uncomment and point it at the right location, or leave it commented out if the node has no code in this repo (it's infrastructure-only or external).

Step 4 · Edit the REVIEW REQUIRED placeholders

Pull the bot commit down and edit the config like any other file:

git pull
$EDITOR .archrails/config.yml
$EDITOR architecture/system.calm.json

Replace each REVIEW REQUIRED with the right value, delete nodes that don't exist, add ones the inference missed. The Declare nodes and Declare relationships lessons cover the field reference in detail.

Push your edits to the same branch. ArchRails re-validates on each push — the PR check stays red until every placeholder is resolved and every relationship references a real node.

git pull
git commit --allow-empty -m "ci: re-trigger ArchRails review"
git push

Step 5 · Merge and you're live

When the check is green, merge. The next PR opened against a governed branch will be reviewed against this architecture — new dependencies that aren't declared, services that move to undeclared hosts, controls that aren't met — all flagged automatically.

Troubleshooting