Charter — AI-Agent Readiness Scanner

Charter ships a composite GitHub Action that downloads the signed Charter binary, verifies it, runs charter doctor, uploads SARIF to GitHub Code Scanning, and gates the job on the score threshold.

Quickstart

Add this to any workflow:

- uses: use-charter/charter-action@v1
  with:
    threshold: "80"

Full copy-paste workflow:

name: Charter

on:
  pull_request:
  push:
    branches: [main]

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

jobs:
  charter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: use-charter/charter-action@v1
        with:
          threshold: "80"

Charter PR check with code scanning annotations — GitHub Code Scanning — Charter findings as security alerts on a pull request

What the action does

Download the signed Charter binary

Resolves the release tag using the GitHub API, then downloads the Charter binary for the runner platform via gh release download.

Verify the binary

Runs cosign keyless verification of the release checksum bundle, then verifies the sha256 of the downloaded archive against checksums.txt. Controlled by the verify input (default: true).

Run charter doctor

Executes charter doctor --format sarif against the repo at path. Applies the effective threshold from the threshold input or charter.yaml.

Upload SARIF to GitHub Code Scanning

Uploads the SARIF report via github/codeql-action/upload-sarif. Gives you Security tab visibility, inline PR annotations, and a durable scan record. Controlled by the upload input (default: true).

Exit with threshold result

Exits 0 if the score meets the threshold, 1 if it falls below. When fail-below: true (default), an exit 1 fails the job after SARIF upload completes.

SARIF upload completes before the threshold check. Even on a failing score, you still get Code Scanning annotations AND a failed CI check — both useful for triage.

Inputs

string

Minimum score to pass. Empty string defers to charter.yaml policy or the built-in default of 80.Default: "" (defer to config)

string

Repository root path to scan.Default: "."

string

Charter release version to download. Accepts a specific tag like v1.0.0 or "latest".Default: "latest"

boolean

Whether to fail the job when the score is below the threshold.Default: true

boolean

Whether to upload the SARIF report to GitHub Code Scanning. Set to false if you only want gate behavior without Security tab annotations.Default: true

boolean

Whether to verify the downloaded binary with cosign and sha256 before running it.Default: true

string

Optional GitHub Code Scanning category for the SARIF upload. Useful for separating Charter results from other SARIF producers in the same workflow.Default: "" (no category)

Outputs

Output	Description
`exit-code`	`charter doctor` exit code: `0` pass, `1` below threshold, `2` error
`score`	Best-effort final Charter score. May be empty if extraction doesn’t yield a value
`sarif-file`	Path to the generated SARIF file

Required permissions

security-events: write is required for SARIF upload. Without it, findings won’t appear in the GitHub Security tab.If you disable upload (upload: false), you can drop security-events: write. In private repositories, keep actions: read when GitHub Code Scanning upload requires it.

permissions:
  actions: read          # SARIF upload in private repos
  contents: read         # Read repository contents
  security-events: write # Required for SARIF upload

Gate semantics

The action preserves Charter’s CLI exit contract:

Exit code	Meaning	Job result (with `fail-below: true`)
`0`	Score at or above threshold	Pass
`1`	Score below threshold	Fail (after SARIF upload)
`2`	Scan or setup error	Fail

Runner requirements

GitHub-hosted runners are the intended baseline. For self-hosted runners, ensure these tools are available:

bash
gh (GitHub CLI)
POSIX utilities: curl, grep, sed, awk
Archive tools: tar or unzip (platform-dependent)
Checksum tools: sha256sum or shasum
jq (optional — used for score extraction; falls back to grep if absent)

Next steps

Run Charter in GitHub Actions

The step-by-step setup recipe for a PR gate.

charter.yaml Reference

Configure the policy the action reads.

Policy Profiles

Set the threshold once and the full precedence ladder.

Use Charter in a Pre-Commit Hook

Match the CI gate locally.

​Quickstart

​What the action does

​Inputs

​Outputs

​Required permissions

​Gate semantics

​Runner requirements

​Next steps

Run Charter in GitHub Actions

charter.yaml Reference

Policy Profiles

Use Charter in a Pre-Commit Hook

Quickstart

What the action does

Inputs

Outputs

Required permissions

Gate semantics

Runner requirements

Next steps