Skip to content

github-action-review.md

Latest commit

 

History

History
99 lines (71 loc) · 4.86 KB

github-action-review.md

File metadata and controls

99 lines (71 loc) · 4.86 KB
Raw

GitHub Action AI review

AI-assisted ADR review is an explicit opt-in extension of the reusable ADR Guard Action. The default remains deterministic check; enabling review does not change existing validation workflows.

Availability: command: review is published on the moving rodri-oliveira-dev/adr-guard@v1 line since v1.1.6. The examples below are valid for the published Action. The latest exact patch is intentionally not hard-coded; use GitHub Releases or the NuGet badge as the moving source of truth.

Trust boundary

Use provider-backed review only in trusted workflows. Review requires Linux, Docker, and Python 3 on the runner because safe summary/annotation rendering is part of the successful review contract. The Action enforces the following boundaries:

  • pull_request_target is rejected for review;
  • fork pull_request events are rejected before Docker/provider execution;
  • only push, workflow_dispatch, schedule, and same-repository pull_request events may opt in; all other event types are rejected before Docker/provider execution;
  • the checkout is mounted read-only for review;
  • GITHUB_TOKEN and GH_TOKEN are never forwarded to the review container;
  • only the credential environment variable associated with the selected provider is forwarded, and only by variable name;
  • no PR comments or write-token operations are performed;
  • workflows need only permissions: contents: read.

For untrusted contributions, run deterministic check on the pull request and perform provider-backed review after merge or from a separately trusted/manual workflow.

Inputs

Set command: review and provide:

Input Required Default Purpose
review-target yes empty Repository-relative ADR Markdown file.
provider yes empty openai, anthropic, gemini, or openai-compatible.
model yes empty Provider model identifier.
endpoint only for compatible providers when required by the CLI empty Explicit OpenAI-compatible endpoint.
context-files no empty Newline-delimited repository-relative .md/.txt files.
include-existing-adrs no false Opt in to bounded existing-ADR context.
policy no advisory advisory or deterministic enforce.
policy-file with policy: enforce empty Repository-relative deterministic policy JSON.

Provider credentials are not Action inputs. Supply the selected credential as an environment variable on the Action step, for example OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}.

Trusted example

name: Trusted ADR AI review

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Review selected ADR
        uses: rodri-oliveira-dev/adr-guard@v1
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        with:
          command: review
          review-target: docs/adr/0007-cache-strategy.md
          provider: openai
          model: gpt-5
          context-files: |
            docs/architecture/security.md
            docs/architecture/availability.txt
          policy: advisory

A same-repository pull_request may also run review when the workflow intentionally provides a provider credential. Fork PRs are blocked even if the workflow is misconfigured to expose review inputs.

Network and filesystem behavior

check and index preserve the existing --network=none behavior. Provider-backed review requires outbound network access, so only that command runs without the Docker --network=none restriction.

The review container root filesystem and entire checkout remain read-only. Review does not write ADRs, status changes, indexes, or report files.

Reporting and exit behavior

Successful review is requested from the CLI as versioned JSON and converted into a GITHUB_STEP_SUMMARY.

Follow-up findings are emitted as GitHub warning annotations only when their evidence source maps to a verified selected local file. The Action does not invent line numbers. Findings without a verified local path, missing context, and uncertainty remain advisory summary text.

The Action preserves the CLI exit contract:

  • 0: review completed; AI findings remain advisory;
  • 1: selected ADR failed deterministic structural validation;
  • 2: invalid Action/CLI configuration;
  • 3: provider, transport, cancellation, or operational failure;
  • 4: explicit deterministic policy enforcement failed.

Exit code 4 is distinct from model findings. A provider failure never becomes a clean-review result.

Pull-request reporting

This first iteration intentionally uses step summaries and file annotations only. It does not create or update PR comments and therefore does not require pull-requests: write or another write permission.