Add a Charter gate to every pull request and upload SARIF findings to GitHub Code Scanning.
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.
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
2
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.
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
The threshold workflow input wins over anything in charter.yaml, which wins over the built-in default of 80. For the full precedence ladder, see Policy Profiles.
3
View results in the GitHub Security tab
After the workflow runs, Charter findings appear in the GitHub Security tab as code scanning alerts:
GitHub Code Scanning — Charter findings as security alerts
Each finding includes:
the rule ID and severity
the file and line where Charter detected the issue
a link to the rule documentation
4
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:
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.
