GitHub Action wrapper for planner gates and scope-json.

• Runs cargo rail plan in planner-owned GitHub transport mode.
• Publishes planner gates and scope-json for job gating.
• Keeps CI behavior aligned with local plan + run workflows.

Minimum planner contract: cargo-rail >= 0.11.0.

name: CI
on: [push, pull_request]

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - uses: loadingalias/cargo-rail-action@v4
        id: rail
        with:
          version: "0.11.0"

      - name: Run targeted tests
        if: steps.rail.outputs.test == 'true'
        env:
          SCOPE_JSON: ${{ steps.rail.outputs.scope-json }}
        run: |
          MODE=$(echo "$SCOPE_JSON" | jq -r '.mode')
          if [ "$MODE" = "workspace" ]; then
            cargo nextest run --workspace
          elif [ "$MODE" = "crates" ]; then
            mapfile -t CRATES < <(echo "$SCOPE_JSON" | jq -r '.crates[]')
            ARGS=()
            for crate in "${CRATES[@]}"; do
              ARGS+=(-p "$crate")
            done
            cargo nextest run "${ARGS[@]}"
          else
            echo "planner enabled test surface, but no package-scoped work was selected"
          fi

      - name: Run docs pipeline
        if: steps.rail.outputs.docs == 'true'
        run: cargo rail run --since "${{ steps.rail.outputs.base-ref }}" --surface docs

Use the stable major tag @v4, or pin a commit SHA for maximum reproducibility. Pin version for deterministic cargo-rail installs.

The action handles shallow checkouts intentionally: raw commit SHAs are fetched directly when possible, and broader history fetch only happens when a branch-based comparison still needs merge-base history.

Optional args examples:

# Explain plan decisions in job logs
- uses: loadingalias/cargo-rail-action@v4
  with:
    args: '--explain'

# Use different comparison ref
- uses: loadingalias/cargo-rail-action@v4
  with:
    since: 'origin/develop'

Gates are boolean outputs (true/false) used in job conditions. They answer: "should this CI surface run?"

How gates work:

1. The planner (cargo rail plan) analyzes changed files against your .config/rail.toml rules
2. It classifies changes into surfaces: build, test, bench, docs, infra
3. The action publishes these as GitHub Action outputs: build=true, test=false, etc.
4. You use these in job if: conditions to skip unnecessary work

Why gates exist:

• Deterministic: same plan locally and in CI (run cargo rail plan --merge-base to preview)
• Configurable: you define infrastructure files, doc-only paths, etc. in rail.toml
• Composable: combine gates (if: steps.rail.outputs.build == 'true' || steps.rail.outputs.infra == 'true')

Modes control what outputs are published:

• minimal (default): gates, scope-json, base-ref, and per-custom-surface booleans
• debug: minimal outputs plus plan-json

Includes all minimal outputs plus the full planner contract.

Note: Most workflows should use minimal mode. scope-json is the execution handoff; use it for package selection in scripts and jobs. plan-json is forensic/debug output only.

Example:

- name: Show targeted crates
  run: echo '${{ steps.rail.outputs.scope-json }}' | jq -r '.crates[]'

Custom surfaces are exported as custom_<name> outputs. Example:

- name: Run benchmark suite
  if: steps.rail.outputs.custom_benchmarks == 'true'
  run: cargo bench --workspace

The action tries installation methods in this order:

1. Cached binary (fastest) — uses GitHub Actions cache (actions/cache)

   • Why: Subsequent runs on same runner are instant (no download)
   • Cache reuse requires exact version match; when version: latest, the action resolves latest first, then compares

2. Release binary (fast) — downloads from GitHub Releases

   • Why: Pre-built binaries for all supported platforms, verified against SHA256SUMS
   • Supports all platforms except macOS Intel (see below)

3. cargo-binstall (fallback) — installs via binstall if available

   • Why: Faster than cargo install (downloads binary instead of compiling)
   • Used when platform is unsupported for release binaries

4. cargo install (slowest, last resort) — compiles from source

   • Why: Guaranteed to work on any platform with Rust toolchain
   • Adds ~2-5 minutes to workflow run time

Default is required: download SHA256SUMS and verify binary integrity.

Why: Supply chain security. Detects corrupted downloads and tampering.

Options:

• required (default): fail if checksum missing or mismatched
• if-available: verify if SHA256SUMS exists, skip if not (for pre-release testing)
• off: skip verification (not recommended for production)

macOS Intel (x86_64-apple-darwin) binaries are not published in releases.

Why: GitHub Actions deprecated macos-latest Intel runners in 2024. All macOS runners are now ARM (macos-14, macos-15). Publishing Intel binaries wastes release bandwidth for a platform no longer used in CI.

Workaround: The action falls back to cargo-binstall or cargo install on Intel Macs (primarily for local testing, not CI).

Action + planner flow validated on production repos with real merge history:

Validation forks: cargo-rail-testing — full configs, integration guides, and reproducible artifacts.

Real-world benefits:

• Docs-only PRs skip build/test entirely (run only docs checks)
• Infrastructure changes (CI config, scripts) trigger full rebuild (no false-negatives)
• Isolated crate changes run targeted tests (not entire workspace)
• Plan matches local behavior (cargo rail plan --merge-base previews CI gates)

Measured impact (last 20 commits per repo):

Each fork includes:

• .config/rail.toml — production-ready config with custom surfaces
• docs/cargo-rail-integration-guide.md — step-by-step CI integration with workflow examples
• docs/CHANGE_DETECTION_METRICS.md — measured impact analysis on recent commits

Reproducible command matrix and examples live in cargo-rail:

• https://github.com/loadingalias/cargo-rail/blob/main/examples/validation-protocol.md
• https://github.com/loadingalias/cargo-rail/tree/main/examples/change_detection

• Action issues: GitHub Issues
• Core tool: loadingalias/cargo-rail

See CONTRIBUTING.md.

See SECURITY.md.

See CODE_OF_CONDUCT.md.

Licensed under MIT.