Use in CI

adrkit ships two GitHub Actions from this repository. Both run with only the default GITHUB_TOKEN, hold no database, and never approve anything — they read the corpus and write a comment or an issue.

GitHub Marketplace

The governing-decisions Action has a repository-root Marketplace entry point available beginning with v0.13.0. The established mbeacom/adrkit/packages/ci@<ref> form remains supported, including through its moving v0 tag. Root Marketplace examples use immutable release tags because recovery may move v0 to a release from before the root alias. GitHub lists only root Action metadata, so the queue Action remains nested.

Comment governing decisions on a PR

The packages/ci Action reads a pull request’s changed files, resolves which accepted decisions govern them via each record’s affects matchers, validates any changed ADR records, and posts a single comment. It is read-only and comment-only; on a read-only fork token it degrades to a log notice instead of failing the job.

.github/workflows/adr.yml

name: ADR governing decisions

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  governing-decisions:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mbeacom/adrkit@v0.13.0
        # with:
        #   dir: docs/adr          # ADR corpus directory (default: docs/adr)
        #   token: ${{ github.token }}

The established mbeacom/adrkit/packages/ci@v0 nested form remains supported.

The Action updates its existing comment on later pushes, so each pull request keeps one current governing-decisions comment. No additional token environment variable is required when using the default GITHUB_TOKEN.

The comment reports marker results separately from governing decisions. Marker scan health lists changed files that could not be inspected (absent, unreadable, out-of-tree, or skipped at the scan cap), so an empty marker result is not mistaken for a healthy scan. It also reports declaration overflow after the 64-per-file or 10,000-per-batch safety limits. Marker claims needing attention lists @adr claims that either did not resolve in this corpus or resolved to superseded, rejected, or deprecated records. Both sections are bounded and advisory: they never affect the Action’s exit status, and changed-record validation errors retain priority if the comment reaches GitHub’s size limit. Keep the default checkout rooted at GITHUB_WORKSPACE; if a workflow checks out elsewhere, marker health will identify files the Action could not inspect.

The Marketplace form is pinned to the immutable v0.13.0 release. For the nested compatibility form, v0 is a moving major tag; pin an immutable release tag or commit SHA when maximum reproducibility matters.

Comments from before the upgrade

The Action is comment-only and deletes nothing, so duplicate comments a pull request already accumulated stay where they are. It updates the newest of them and leaves the rest for you to delete once.

Pinning a release tag by SHA

The v* release tags are annotated, so refs/tags/v0.13.0 resolves to a tag object rather than a commit, and uses: rejects that SHA. Pin the commit the tag points at:

git rev-parse v0.13.0^{commit}
# or, over the API — this endpoint peels the tag for you:
gh api repos/mbeacom/adrkit/commits/v0.13.0 --jq .sha

Note that GET /git/ref/tags/{tag} does not peel: its object.sha is the tag object, which is exactly the value uses: will not take.

Publish the ARB operations queue

The packages/ci/queue Action creates or updates exactly one dedicated issue whose body carries the deterministic adr queue Markdown report — the tiers, SLA state, approvals, and objections projected from the corpus’s review metadata. It needs issues: write.

.github/workflows/adr-queue.yml

name: ADR ARB queue

on:
  schedule:
    - cron: '0 13 * * 1' # Monday 13:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  arb-queue:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mbeacom/adrkit/packages/ci/queue@v0
        # with:
        #   dir: docs/adr
        #   issue-title: ADR ARB Queue

Pinning the queue Action

@v0 is a moving major-version tag. Pin the commit SHA when you need a byte-immutable reference. Resolve the current commit without an adrkit checkout: gh api repos/mbeacom/adrkit/commits/v0 --jq .sha.

The managed issue’s body is the same report you get locally:

# ARB Queue — 2026-07-28

Corpus fingerprint: `0cd56b8…10e3eb6`
8 item(s) | 0 corpus finding(s) | 0 item(s) with findings

## Queue Items

| # | ID | Title | Tier | SLA State | Deadline | Approvals | Objections |
|---|----|-------|------|-----------|----------|-----------|------------|
| 1 | 0003 | Ship as a Spec Kit extension plus a standalone CLI … | arb | within-sla | 2026-08-27 | 0/- | 0 |
| 2 | 0006 | License Apache-2.0 with a DCO and develop in a single … | arb | within-sla | 2026-08-27 | 0/- | 0 |

Identical inputs produce byte-for-byte identical output, so a re-run only changes the issue when the corpus actually changed. Run the same projection locally with adr queue, or publish its totalItems as a README badge — see Badges.