Connect GitHub - ArchDocs

Connect GitHub to keep diagram YAML next to the code it describes and review diagram changes in the same pull request. You can also ask architecture questions in comments and flag pull requests whose mapped documentation may need an update.

Installing and managing the connection requires integrations:manage. Bot answers consume your organization's AI credits.

Install the app and connect a file

Open the organization name in the sidebar, then select Organization Settings > GitHub.
Select Install GitHub App. Choose the GitHub account and repositories the app can access, then complete the authorization flow back to ArchDocs.
Under Connect a repository, find your repository and select Connect.
In Import files matching, enter an exact YAML path, such as archdocs/billing.yaml. Select the Connect button that includes the repository name.
Push a change that adds or modifies that file. ArchDocs compiles its diagram YAML and creates or updates the mapped document.

If the repository is missing, select Missing a repository? Adjust GitHub App access and change the app's repository access on GitHub.

The default pattern is archdocs/**.yaml, but a mapping always writes to one document. If the pattern matches several files, a later push can overwrite that document with a different file. Use an exact path when you want one diagram to have one source file.

Keep the repository as the source

Sync runs in one direction: GitHub to ArchDocs. ArchDocs doesn't commit canvas edits back to the repository. A later matching push replaces manual changes to the mapped document.

For an exact-path mapping, the document's Synced from GitHub badge links to its source. Connected repositories shows the file pattern and last sync time. Deleting a source file doesn't delete the imported document.

Ask the comment bot

In a new issue or pull request comment in a connected repository, mention the installed bot's handle with a question. For an app installed as @archdocs-bot:

@archdocs-bot which services depend on Billing Service?

The bot answers from the organization's documented architecture and replies in the issue or pull request. If the organization has reached its AI credit limit, it posts a notice instead of an answer.

Check documentation drift in pull requests

The drift check uses mappings you write. It doesn't infer which documents describe changed code, or verify that a diagram describes the implementation correctly.

Commit an .archdocs.yml file to your repository. For Lanefold, a fictional freight company, this example maps Billing Service code to its diagram YAML:

version: 1
severity: neutral
skipDrafts: true
mappings:
  - name: Billing Service
    paths:
      - 'services/billing/**'
    source: 'archdocs/billing.yaml'

When a pull request changes matching code, this mapping is fresh if the pull request also changes archdocs/billing.yaml. Otherwise it is stale. A YAML edit counts even if it doesn't address the code change, so review the diagram as part of the pull request.

To check a hosted document instead, replace source with docs:

version: 1
mappings:
  - name: Billing Service
    paths:
      - 'services/billing/**'
    docs:
      - 'PASTE-DOCUMENT-ID-HERE'

Under Docs drift check in the GitHub settings page, find the document and select Copy id. Replace the placeholder before committing. Hosted documents count as fresh when their last update is on or after the pull request's base commit date. Any update counts, including an unrelated edit.

The parser accepts these configuration fields:

Field	Meaning
`version`	Required. Must be `1`.
`severity`	`neutral` by default, or `failure` for stale findings. A mapping can override it.
`skipDrafts`	`true` by default. Set `false` to evaluate draft pull requests.
`ignore`	Extra file globs to ignore.
`ignoreDefaults`	`true` by default. Set `false` to remove the built-in ignores for files such as tests, Markdown, and lockfiles.
`mappings`	Required list of mappings. Each needs nonempty `paths` and at least one of `source`, `docs`, or `objects`.
`name`	Optional mapping name, used in reports and acknowledgements. Defaults to the first path.
`source`	Diagram YAML in the repository. Takes precedence over `docs` and `objects`.
`docs`	Hosted document IDs or exact, unique document names.
`objects`	Object IDs. Checks documents attached to each object.
`minChangedFiles`	Matching files needed to activate a mapping. Defaults to `1`.

name, source, docs, objects and minChangedFiles go inside each mapping. Unknown fields or invalid values produce a neutral result. The accepted config locations, in priority order, are .archdocs.yml, .archdocs.yaml, .github/archdocs.yml, and .github/archdocs.yaml. Without a config file, ArchDocs posts no check.

The hosted check is named archdocs / docs drift. A document the check can't resolve doesn't count as stale.

Acknowledge an intentional finding

Add a line to the pull request description when a mapped diagram needs no change:

archdocs-ack: Billing Service - internal refactor, documented contract unchanged

The target is the mapping name. Editing the description re-runs the check; acknowledged mappings don't count toward the stale result. To skip drift evaluation, put [skip archdocs] in the pull request title or description. The check still posts a neutral result.

Disconnect

To stop importing a mapping, use its trash icon under Connected repositories. To disconnect the organization, select Disconnect and confirm. Imported documents remain, while push imports and bot answers stop for that organization. Removing the app from GitHub is a separate uninstall.