GitHub

GitHub Actions

The inputs and outputs of the two Actions that run archboard check and report the architecture of a pull request. Both install the published CLI, or run the one that cli names, and run only its commands.

Use an Action by its path in this repository. The examples pin it to the commit of v0.5.0, with the tag in a comment. Pin each Action to a commit, as you pin any third-party Action, because a tag can move and the pull-request Action holds a token that can comment. Pin version to the CLI release that your team runs, the way you pin a compiler. Both Actions set up Node.js, install archboard with npm, and stop the Archboard server when they finish. With cli, an Action runs that CLI instead of installing one.

Archboard check #

Run archboard check on a repository's architecture model. The step fails on a semantic diagnostic or a warning, puts each finding on the pull request's diff as an annotation with excerpts of the code and the manifest it rests on, and writes the findings to the job summary. It needs only contents: read.

The guide: The check as a gate.

miklschmidt/archboard/actions/check
- uses: actions/checkout@v5
- uses: miklschmidt/archboard/actions/check@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0
with:
version: 0.5.0
fail-on: warning

Inputs

Input What it does
version optional The version of archboard to install, such as 0.2.0, or latest. Leave it out to install the version of the archboard release that this Action comes from. cli replaces it. No default: empty when you leave it out.
cli optional A CLI to run instead of installing archboard: a path to its executable, relative to the workspace. Archboard's own repository gives ./bin/archboard, built from the commit under review. Leave it out to install version. No default: empty when you leave it out.
working-directory optional The directory, relative to the workspace, that holds the checkout whose vault is checked. Default ..
checks optional Which checks to run. One of all, semantics, code or embeds. Default all.
args optional Extra arguments for archboard check, such as --every-draft or --state "Queued fulfilment". Quotes group words. No shell runs them. No default: empty when you leave it out.
repos optional Paths of more checkouts, one per line and relative to the workspace, to register before the check. A platform setup that keeps its infrastructure in another repository lists that checkout here, so a network hop can be read on both sides. No default: empty when you leave it out.
fail-on optional warning fails the step when the check exits 1, which means a semantic diagnostic or a warning remains. never reports findings and never fails on them. A check that cannot run (usage error, refusal, server unreachable, or a checkout without a vault when the checks read one) always fails the step. Default warning.
allow-codes optional Finding or diagnostic codes, separated by newlines or commas, that are shown and never block. They still get annotations and appear in the job summary, marked allowed. With fail-on: warning the step fails only when an error or a warning with another code remains. No default: empty when you leave it out.
node-version optional The Node.js version to run the CLI with. The CLI needs 22.18 or later. Default 22.

Outputs

Output What it holds
exit-code The exit status of archboard check. 0 passed, 1 findings remain, 2 or more could not run.
errors The number of semantic diagnostics.
warnings The number of warnings of the code check and the embeds check.
information The number of information findings, which never fail the check.
report The path of the saved JSON answer of archboard check.

Archboard pull request #

Comment on a pull request with its architecture as text: the proposal it carries, the footprint of the change against the plan, and a link to the vault. Optionally warn or fail when modules change outside the plan, or when the proposal adds modules that bind no code that it adds. It warns when the archboard-pr section of the description draws a Mermaid chart. Runs on pull_request events and needs a checkout with fetch-depth: 0. The job needs contents: read and pull-requests: write, or only contents: read when report-file takes the report in place of the comment.

The guide: Architecture on pull requests.

miklschmidt/archboard/actions/pull-request
- uses: actions/checkout@v5
with:
fetch-depth: 0
- uses: miklschmidt/archboard/actions/pull-request@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0
with:
version: 0.5.0
out-of-plan: warn

Inputs

Input What it does
version optional The version of archboard to install, such as 0.2.0, or latest. Leave it out to install the version of the archboard release that this Action comes from. cli replaces it. No default: empty when you leave it out.
cli optional A CLI to run instead of installing archboard: a path to its executable, relative to the workspace. Archboard's own repository gives ./bin/archboard, built from the commit under review. Leave it out to install version. No default: empty when you leave it out.
working-directory optional The directory, relative to the workspace, that holds the checkout whose vault is read. Default ..
repos optional Paths of more checkouts, one per line and relative to the workspace, to register first. A vault that binds modules in other repositories needs them to read their footprint. No default: empty when you leave it out.
node-version optional The Node.js version to run the CLI with. The CLI needs 22.18 or later. Default 22.
state optional The proposal of this pull request, by identity or name. Without it the action reads the archboard-pr marker in the pull request description, then uses the only draft proposal the model has, and otherwise reports the change without a plan. No default: empty when you leave it out.
out-of-plan optional What modules that changed outside the plan do. warn annotates and says so in the comment, fail fails the step unless the pull request carries the override label, and off does not judge. With no proposal there is no plan, so nothing is ever out of plan. Default warn.
preexisting optional What modules that the proposal adds, but whose bound code the pull request does not add, do. A picture of the proposal marks such a module as added although the diff adds no code for it. The comment lists them in every mode. warn annotates, fail fails the step unless the pull request carries the override label, and off does not judge. A module bound to a directory that the pull request adds a file to is not counted. Default warn.
override-label optional The label that lets a pull request through when out-of-plan or preexisting is fail. Default archboard: out of plan.
report-file optional A file that takes the report in place of the comment. A relative path starts at the workspace. The Action creates missing parent directories and writes the Markdown that it would post to that file, its hidden marker included. It then posts and edits no comment and writes no job summary. A later step puts the report where the team wants it, such as the job summary. The plan check annotates and fails the step as it does without this input. A write failure fails the step without setting report. No default: empty when you leave it out.
github-token optional The token that comments on the pull request. It needs pull-requests: write, unless report-file is set. The job also needs contents: read. Default ${{ github.token }}.

Outputs

Output What it holds
report The absolute path of the file that holds the report, when report-file is set.
Docs

Type to search every page, command and schema.