Five-minute GitHub setup

This guide lets a repository run the released AIV CLI without building Maven or copying AIV source. It assumes a hardened AIV release has been published to Maven Central and a full immutable Action commit SHA is available.

Before you begin

1. Create an explicit policy

Run the released CLI once locally or add this starter policy directly:

# .aiv/config.yaml
schema_version: 1
fail_fast: false

gates:
  - { id: syntax, enabled: true }
  - { id: invariant, enabled: true }
  - { id: dependency, enabled: true }
  - { id: package-existence, enabled: false }
  - { id: test-adequacy, enabled: true }
  - { id: security, enabled: false }
  - { id: design, enabled: false }
  - { id: density, enabled: true, severity: warn }
  - { id: cohesion, enabled: true, severity: warn }
  - { id: duplication, enabled: true, severity: warn }
  - { id: doc-integrity, enabled: false }
  - { id: pr-metadata, enabled: false }
  - { id: license-header, enabled: false }
  - { id: external, enabled: false }
  - { id: rules, enabled: false }
  - { id: jev, enabled: false }
  - { id: review-routing, enabled: false }
  - { id: change-policy, enabled: false }

Commit the policy to the base branch. Strict AIV runs read policy from that protected base commit, not from a proposed pull request.

2. Add the workflow

Create .github/workflows/aiv.yml. Replace both placeholder values with the released CLI version and its full immutable Action commit SHA.

name: AIV

on:
  pull_request:

permissions:
  contents: read
  checks: write
  security-events: write

jobs:
  aiv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          fetch-depth: 0

      - name: Run AIV
        id: aiv
        continue-on-error: true
        uses: vaquarkhan/aiv-integrity-gate@<IMMUTABLE_ACTION_COMMIT_SHA>
        with:
          base-ref: origin/$
          aiv-version: "<RELEASED_VERSION>"
          output-json: aiv-report.json
          output-sarif: aiv-results.sarif
          publish-github-checks: "true"

      - name: Upload SARIF
        if: always() && steps.aiv.outcome != 'skipped'
        uses: github/codeql-action/upload-sarif@5895b2c9be147bc7f1c75ce72c5cb577febb1907
        with:
          sarif_file: aiv-results.sarif

      - name: Preserve the AIV result
        if: always()
        run: test "$" = success

3. Open a pull request

AIV reads the complete base-to-head diff, freezes the .aiv policy from the protected base ref, and emits:

Start with blocking syntax and invariant rules only. Keep design, change policy, external tools, JEV, and review routing advisory or disabled until you have repository-specific calibration evidence.

Optional labels and comments

Add pull-requests: write only if needed. Then add these Action inputs:

          label-pr-on-advisory: "true"
          label-deterministic-findings: "true"
          deterministic-findings-label: "aiv:findings"
          comment-deterministic-findings: "true"
          label-review-tier: "true"

The legacy label-ai-slop, ai-slop-label, and comment-ai-slop inputs remain supported for v1 compatibility. New policies should use deterministic-findings names and labels.

Enable JEV separately

JEV is optional, advisory only, and requires a protected base policy plus a trusted AWS OIDC workflow. Follow JEV on Amazon Bedrock. Do not put AWS credentials in the ordinary pull-request AIV workflow.

Troubleshooting

For the full configuration surface, see DEVELOPER-CONFIGURATION.md and DEPLOYMENT.md.