GitHub Action consumer guide

Publication status: the reusable Action is published, and the compatibility tag v1 is published and moving. The public v1 line supports check, index, and opt-in review since v1.1.6; new and draft remain CLI/container-only workflows. The GitHub Marketplace listing was independently reachable without authentication on 2026-10-09.

Impact release status: the impact inputs are prepared for coordinated v1.5.0 publication but are not yet available from the current public @v1 runtime. Do not use the example below until that coordinated release is verified.

ADR Guard’s composite Action runs the published ADR Guard container. Consumers do not need the .NET SDK. They need a Linux runner with Docker and must check out the repository first; opt-in review additionally requires Python 3 on the runner for safe summary/annotation rendering.

Inputs

Input	Default	Accepted values
path	docs/adr	Repository-relative ADR directory inside GITHUB_WORKSPACE. Absolute paths, missing directories, .. traversal, and symlink escapes are rejected.
command	check	check, index, explicit review, or explicit impact.
version	empty	Optional exact runtime image version in X.Y.Z or vX.Y.Z form. Required when the Action source is pinned by commit SHA or branch.
review-target	empty	Repository-relative ADR Markdown file; required for review.
provider	empty	Review provider; required for review.
model	empty	Provider model identifier; required for review.
endpoint	empty	Optional OpenAI-compatible endpoint.
context-files	empty	Optional newline-delimited repository-relative .md/.txt review context.
include-existing-adrs	false	Explicit opt-in to bounded existing-ADR review context.
policy	advisory	advisory or deterministic enforce.
policy-file	empty	Deterministic policy JSON; required with policy: enforce.
base-ref	empty	Explicit Git base reference; required for impact. The checkout must contain enough history to calculate a merge base.
impact-map	empty	Repository-relative ADR-to-code mapping JSON; required for impact. Traversal and symlink escapes are rejected.

The CLI exit contract is preserved: 0 success, 1 ADR validation failure, 2 usage/input error, 3 operational/provider failure, and 4 deterministic review-policy failure.

Provider-backed review is optional and does not alter the default check behavior. See GitHub Action AI review for credentials, trusted events, summaries, annotations, and fork/pull_request_target restrictions.

Architecture impact analysis is also opt-in and does not change the default check behavior. It is read-only, runs with networking disabled, forwards no provider or GitHub credentials, and writes a bounded advisory GITHUB_STEP_SUMMARY. The caller owns checkout history; use fetch-depth: 0 or another explicit depth that contains the selected base and merge base. Fork pull requests can use this deterministic mode with permissions: contents: read and no secrets.

permissions:
  contents: read

steps:
  - name: Checkout with comparison history
    uses: actions/checkout@v7
    with:
      fetch-depth: 0
      persist-credentials: false

  - name: Inspect architecture impact
    uses: rodri-oliveira-dev/adr-guard@v1
    with:
      command: impact
      base-ref: origin/main
      impact-map: .adrguard-impact.json

The Action validates that the selected runtime image exposes the impact CLI contract. An older exact image pin fails as an operational error instead of falling back to latest. Missing history or a disconnected base also returns exit code 3; affected or unmapped changes still return 0 because the report is advisory.

The stable JSON remains in the raw, workflow-command-suspended log. If a retained JSON artifact is required, run the same exact-version container explicitly with the checkout mounted read-only, redirect impact --format json to ${RUNNER_TEMP}/adr-impact.json, and then opt in to actions/upload-artifact in the consumer workflow. The Action does not create or upload an artifact implicitly. See the complete read-only example.

Pull-request validation

Published @v1 example:

name: ADR validation

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  adr-guard:
    name: ADR Guard
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Validate ADRs
        uses: rodri-oliveira-dev/adr-guard@v1
        with:
          path: docs/adr
          command: check

A file copy of this workflow lives at examples/github-action-pr.yml.

Main-branch validation

Use the same read-only validation after merges to main:

name: ADR validation

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  adr-guard:
    name: ADR Guard
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Validate ADRs
        uses: rodri-oliveira-dev/adr-guard@v1
        with:
          path: docs/adr
          command: check

A file copy of this workflow lives at examples/github-action-main.yml.

Validation output and annotations

Validation failures keep the CLI diagnostics in the raw log. Recognized ADR001–ADR009 diagnostics are converted into escaped GitHub file annotations when the diagnostic path can be verified inside the selected ADR directory. The CLI does not provide reliable line numbers, so the Action does not invent them.

The Action also writes a compact GITHUB_STEP_SUMMARY with the outcome, exit code, total diagnostics, and per-rule counts. At most 50 file annotations are emitted per run; the raw log retains all diagnostics.

check versus index

check is read-only: the complete checkout is mounted read-only.

index intentionally writes the generated README.md inside the selected ADR directory. The rest of the checkout remains read-only. A common CI pattern is:

- name: Generate ADR index
  uses: rodri-oliveira-dev/adr-guard@v1
  with:
    path: docs/adr
    command: index

- name: Ensure generated index is committed
  run: git diff --exit-code -- docs/adr/README.md

The @v1 reference above uses the published moving major compatibility tag.

Version pinning

Choose the pinning mode according to your update policy:

• @v1.2.3: immutable Action source for that exact release and exact runtime image :1.2.3.
• @v1: moving compatibility reference that follows newer successful v1.x.y releases and runtime image :1.
• @<commit-sha>: immutable Action source; specify version: 1.2.3 explicitly because a commit SHA does not encode the runtime image version.

There is never an implicit fallback to latest.

See GitHub Action release policy and security model.

Permissions and required checks

The Action itself only needs repository contents to have been checked out. A validation workflow can use:

permissions:
  contents: read

To make ADR validation mandatory before merge, first run the workflow at least once so GitHub knows the check name. Then configure the repository’s branch rules or ruleset for main and require the status check produced by the ADR Guard job. Keep the job name stable so the required-check rule continues to match.

Troubleshooting

If the Action reports exit code 2, check the path, command, and version/ref combination. Paths must remain inside the checkout.

Exit code 3 means an operational failure such as Docker being unavailable, the selected image being unavailable, or Python 3 being unavailable for opt-in review. The supported environment is a Linux runner with a working Docker daemon; review additionally requires Python 3.

For index, the runner must be non-root because the Action deliberately refuses to execute the writable container as UID 0.

If a SHA or branch ref is used, provide an exact version input. When @v1 is used, the Action source follows the published v1 compatibility tag and resolves the matching :1 runtime image.

Releases and Marketplace

Release notes are published on the repository’s Releases page.

Marketplace listing: ADR Guard - Architecture Decision Validator, independently reachable without authentication on 2026-10-09. The published @v1 Action is tested in isolated fixtures; the independent poc-arquitetura rerun against released @v1 passed, including expected ADR005 failure and annotation. See external verification evidence, the historical public release audit, and the Marketplace publication checklist. For support and vulnerability reporting, see ../SUPPORT.md and ../SECURITY.md.