Skip to content

github-action.md

Latest commit

 

History

History
234 lines (167 loc) · 13.2 KB

github-action.md

File metadata and controls

234 lines (167 loc) · 13.2 KB
Raw

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 and drift release status: the impact inputs are available from the coordinated public v1.5.0 / @v1 runtime. drift inputs are available in the published exact Action @v1.10.0 and in the moving @v1 reference (currently v1.10.0); the older exact @v1.9.0 does not expose them. CLI 1.11.0 is an unpublished candidate; native MADR generation is a CLI command and is not exposed by the Action. Verify the selected Action ref and matching container version before use.

ADR Guard's composite Action runs the selected 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; review, impact, and read-only drift additionally require Python 3 on the runner for bounded summary 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, explicit impact, or explicit drift.
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.
drift-rules empty Repository-relative architecture fitness rules JSON; required for drift.
drift-policy advisory advisory or deterministic enforce; applies only to drift.
drift-baseline empty Optional repository-relative existing drift baseline JSON. The Action never creates or updates it.
drift-evidence empty Optional newline-delimited repository-relative external evidence JSON files; at most 20 distinct files.

The CLI exit contract is preserved: 0 success or a conclusive advisory result, 1 ADR validation failure, 2 usage/input error, 3 operational/provider failure or inconclusive drift, and 4 deterministic policy failure from review or enforced drift.

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.

Architectural drift verification (v1.10.0+)

The published Action adapts the existing adr-guard drift CLI contract; it does not implement a second fitness-rule engine. The checkout is mounted read-only, networking is disabled, inputs are validated inside GITHUB_WORKSPACE, and no credentials or GitHub tokens are forwarded. The selected image is probed for drift --help before consumer data is mounted.

permissions:
  contents: read

steps:
  - uses: actions/checkout@v7
    with:
      persist-credentials: false

  - name: Verify ADR-backed architecture rules
    uses: rodri-oliveira-dev/adr-guard@v1.10.0
    with:
      command: drift
      drift-rules: .adrguard-fitness.json
      drift-policy: enforce
      # drift-baseline: drift-baseline.json
      # drift-evidence: |
      #   evidence/unit-tests.json
      #   evidence/integration-tests.json

drift-policy defaults to advisory. A conclusive pass or advisory/baselined violation returns 0; an invalid Action/CLI input returns 2; missing or inconclusive evidence remains unknown and returns 3; enforce returns 4 only when the CLI identifies a new gate-enabled deterministic static violation. The bounded summary labels pass, violation, and unknown but never recomputes policy or turns uncertainty into compliance. The original CLI exit always wins, including if summary rendering fails.

drift-baseline is read-only. Baseline creation and replacement remain explicit owner operations through the CLI and are deliberately not exposed by the Action. drift-evidence accepts up to 20 existing JSON files, one repository-relative path per line. Traversal, absolute paths, duplicates, non-JSON files, missing files, and symlink escapes are rejected before Docker execution. See the published workflow example and architectural drift guide.

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.

Real GitHub Actions demo

The ADR Guard demo repository preserves a complete validation cycle in pull request #1:

  1. A valid Architecture Decision Record is intentionally changed.
  2. Its required Consequences section is removed.
  3. The Action runs check, which reports ADR005 because the section is missing.
  4. GitHub Actions records the failed run with exit code 1.
  5. The ADR is corrected by restoring balanced consequences.
  6. The next validation passes with exit code 0.

The failure is intentional demonstration history, not an ADR Guard defect. The pull request has been merged, but both runs remain available for inspection. The demo repository contains the reproducible workflow and tutorial; this guide does not duplicate them.

The check mode applies deterministic documentation rules. It does not approve the ADR, assess the technical merit of its decision, or replace human architectural review.

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, Python 3 being unavailable for bounded review/impact/drift reporting, or a valid drift result remaining inconclusive. The supported environment is a Linux runner with a working Docker daemon.

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.