> ## 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.
# GitHub Action
> The use-charter/charter-action@v1 composite action — runs charter doctor, uploads SARIF to GitHub Code Scanning, and gates PRs on the score threshold.
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:
```yaml theme={null}
- uses: use-charter/charter-action@v1
with:
threshold: "80"
```
Full copy-paste workflow:
```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"
```
## What the action does
Resolves the release tag using the GitHub API, then downloads the Charter binary for the runner platform via `gh release download`.
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`).
Executes `charter doctor --format sarif` against the repo at `path`. Applies the effective threshold from the `threshold` input or `charter.yaml`.
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`).
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
Minimum score to pass. Empty string defers to `charter.yaml` policy or the built-in default of `80`.
Default: `""` (defer to config)
Repository root path to scan.
Default: `"."`
Charter release version to download. Accepts a specific tag like `v1.0.0` or `"latest"`.
Default: `"latest"`
Whether to fail the job when the score is below the threshold.
Default: `true`
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`
Whether to verify the downloaded binary with cosign and sha256 before running it.
Default: `true`
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.
```yaml theme={null}
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
The step-by-step setup recipe for a PR gate.
Configure the policy the action reads.
Set the threshold once and the full precedence ladder.
Match the CI gate locally.