GitHub sync and drift

Connect a repository

Install the DesignDoc GitHub App on your organisation and connect a repository to your DesignDoc organisation. If you cannot install an app, a fine-grained personal access token works as a fallback and is checked on a schedule instead of by webhook.

Import ADRs

Point DesignDoc at the folder that holds your ADRs, usually docs/adr. It reads files named like 0007-use-postgres.md or adr-7-use-postgres.md, understands MADR and Nygard-style headings, and maps statuses such as Proposed, Accepted and Deprecated to DesignDoc statuses. Importing again skips files that have not changed, and changes pushed to the folder are picked up on their own.

Export accepted decisions

Export is off until an admin turns it on. When enabled, an accepted decision is written back as a MADR Markdown file in a branch and opened as a pull request. DesignDoc never writes to your default branch and never merges. Exporting sends the decision text to GitHub, so the setting asks you to confirm for organisations that use encryption.

Link a decision to code

On a decision, add links to what it governs:

• A file or folder, such as services/ledger/.
• A glob, such as services/**/payments_*.go.
• A pull request. Merged pull requests that mention a decision are suggested as links.
• The whole repository, for a standard that applies to everything in it. Pick Whole repository when adding the link; it is offered first on standards.

Drift

When a push to the default branch changes a linked path, the decision is flagged Needs re-check. Several pushes in a short time become one flag, and an AI summary compares what changed with what the decision says. Only accepted, implementing and implemented decisions can drift.

A whole-repository link works differently. Every push to the repository, and every merged pull request linked to that decision, lands in the one open flag for the decision: the flag gathers the changed paths and counts the pushes, and no AI summary is written on its own. Editors can ask for one from the flag (Summarise N paths across M pushes); it uses one AI assist, covers every path gathered so far, and can be run again once newer pushes land. The author is told once a day at most. Resolving the flag closes it; the next push opens a new one.

From the banner on the decision you can:

• Re-confirm, with an optional note. This is recorded as a comment.
• Mark stale if the decision no longer reflects the code.
• Supersede to start a new draft that links back and carries the summary.
• Dismiss (admins) if the change is not relevant.

Drift notifications are in-app. Slack nudges are available on Team and Business.