Charter — AI-Agent Readiness Scanner

Use Charter in GitHub Actions when you want every pull request to run the same repo scan your local workflow runs. This guide adds a dedicated Charter workflow, sets the score threshold, uploads SARIF to GitHub Code Scanning, and blocks merges when the score falls below the gate.

Add the workflow file

Create .github/workflows/charter.yaml:

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"

The security-events: write permission is required to upload SARIF to GitHub Code Scanning. Without it, findings won’t appear in the GitHub Security tab, but the threshold gate still works.

Why each permission is present:

Permission	Why it’s needed
`contents: read`	Lets the workflow read the repository
`security-events: write`	Required for SARIF upload to Code Scanning
`actions: read`	May be required for SARIF upload in private repos

Configure the threshold

Set the minimum passing score in the workflow or in charter.yaml. Common values:

Standard (80)
Strict (90)
Defer to charter.yaml

The default for most repos. Enforces the baseline agent-readiness rules without requiring a fully optimized repo.

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

A higher bar for security-sensitive repos, production services, or teams that have resolved the common findings and want to hold the line.

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

Omit the threshold input to let the action defer to whatever policy.threshold or policy.profile is set in your repo’s charter.yaml.

- uses: use-charter/charter-action@v1

Threshold precedence (highest to lowest):

threshold workflow input
policy.threshold in charter.yaml
policy.profile default in charter.yaml
Built-in default: 80

View results in the GitHub Security tab

After the workflow runs, Charter findings appear in the GitHub Security tab as code scanning alerts:

Each finding includes:

the rule ID and severity
the file and line where Charter detected the issue
a link to the rule documentation

Understand exit behavior

Charter preserves its CLI exit semantics through the action:

Exit code	Meaning	Job result
`0`	Score meets or exceeds threshold	Job passes
`1`	Score below threshold	Job fails (with `fail-below: true`)
`2`	Scan or setup error	Job fails

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

If you want annotations without blocking merges, set fail-below: false:

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

Troubleshooting

The Security tab shows no findings after the workflow ran

Confirm security-events: write is present in the workflow permissions block. Also check that the workflow log shows a successful SARIF upload step — look for the upload-sarif action output.

The PR passes even though the score is below the threshold

Check that fail-below is not set to "false". Then confirm the effective threshold by looking at Charter’s output in the workflow log — the threshold in use is printed at scan start.

The action fails before the scan runs

Check that the use-charter/charter-action@v1 ref is published and reachable. On self-hosted runners, confirm bash, gh, curl, tar, and sha256sum are available in the shell environment.

​Troubleshooting

Troubleshooting