> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Run Charter in GitHub Actions
> 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.
Create `.github/workflows/charter.yaml`:
```yaml theme={null}
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 |
Set the minimum passing score in the workflow or in `charter.yaml`. Common values:
The default for most repos. Enforces the baseline agent-readiness rules without requiring a fully optimized repo.
```yaml theme={null}
- 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.
```yaml theme={null}
- 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`.
```yaml theme={null}
- 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](/docs/config/policy-profiles#threshold-precedence).
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
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`:
```yaml theme={null}
- uses: use-charter/charter-action@v1
with:
threshold: "80"
fail-below: "false"
```
## Troubleshooting
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.
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.
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.
## Next steps
Full input, output, and gate-semantics reference for the composite action.
Set a consistent threshold once instead of per-run.
Configure policy and the MCP allowlist at the repo root.
Match the CI gate locally so commits and CI agree.