Scan with GitHub Actions
Run SkillTrust's free scanner in a workflow. Start in report-only mode, then choose whether findings should block after reviewing the signal in your repository.
Quickstart #
Add .github/workflows/skilltrust.yml to a public or private repository. This starting configuration reports findings without failing the job, while installation, input, integrity and scanner errors still fail.
The public v1 compatibility default for report-only is false. Keep the explicit true value while evaluating findings; remove it later only when the repository is ready to block at its configured policy.
fetch-depth: 0 is required for reliable pull-request comparison. pull-requests: write is used only for same-repository PR comments.
name: skilltrust
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
pull-requests: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- id: skilltrust
uses: skilltrust/scan-action@v1
with:
report-only: 'true'
delta: 'true'What the report means #
The heading counts issues in the current head. The next line says whether this Action run passes or fails under its configured policy; a low grade alone does not decide that result.
With delta enabled on a pull request, New in this PR means present in the current head but not its current base. Already on base is still present and still participates in policy. Fixed by this PR means present on the current base and absent from the current head.
The comparison is base versus head, not a memory of earlier runs. A finding added and removed inside the same PR is absent, not fixed. If comparison fails, the complete head result still reports and gates without claiming new, existing or fixed status.
Pull requests and reruns #
Each pull request gets one sticky Action comment. Later commits update that comment in place; another PR gets its own comment. Closing a PR leaves its comment in the closed PR. The Action stores no finding history or suppression state on SkillTrust servers.
Runner files disappear with the GitHub job unless the workflow uploads them. An uploaded result follows that repository's GitHub artifact access and retention settings.
Fork pull requests do not receive the workflow token or an Action comment. Their bounded report remains in Job Summary and an inert log copy. Never switch to pull_request_target to work around this boundary.
Configuration #
All inputs are optional. The quickstart deliberately overrides report-only; the table shows the public v1 defaults.
| Input | Default | Meaning |
|---|---|---|
| path | . | Repository path to scan. |
| fail-on | critical | Severity that makes a finding breach the threshold. |
| fail-on-axis | empty | Comma-separated per-axis grade thresholds. |
| strict-mcp | false | Raise the MCP external-domain rule from medium to high. |
| scan-all | false | Disable scope tightening and .gitignore filtering. |
| comment | true | Post a sticky comment on pull-request runs. |
| warn-on-below-threshold | true | Keep exit 1 as a warning instead of failing. |
| fail-on-no-agent-surface | false | Fail when no supported files were found. |
| report-only | false | Let valid finding exits 1 and 2 pass; errors still fail. |
| delta | false | Compare a pull request with its base; requires full checkout history. |
| telemetry | true | Send the documented coarse run heartbeat; no paths or findings. |
| github-token | github.token | Token used only for pull-request comments. |
| detector-version | v0.10.0 | Detector release; the action tag pins its own default. |
Outputs and exit codes #
The action exposes grade, scan-json-path, findings-count and no-agent-surface. A missing agent surface has no grade; it is not a passing security result.
| Code | Meaning | Default workflow result |
|---|---|---|
| 0 | No findings. | Pass. |
| 1 | Findings, all below configured thresholds. | Pass with warning. |
| 2 | A severity or axis threshold was breached. | Fail. |
| 3 | Bad arguments, unreadable input or an internal tool error. | Fail. |
Keep the complete result #
The comment and Job Summary are bounded for review. The scan-json-path output points to the validated, unmodified JSON on the runner. Upload it explicitly when the full result must remain available after the job.
- if: always() && steps.skilltrust.outputs.scan-json-path != ''
uses: actions/upload-artifact@v4
with:
name: skilltrust-scan-json
path: ${{ steps.skilltrust.outputs.scan-json-path }}Scan scope and privacy #
The action checks supported skill files, project instructions, settings and permissions, hooks, and MCP configuration under path. It honours .gitignore and narrows repository scope unless scan-all is true.
Repository contents and the validated complete JSON stay in the GitHub runner. Temporary files disappear with the job unless the workflow uploads the JSON as an artifact.
Every valid completed scan writes a bounded findings-and-grades report to GitHub Job Summary. A same-repository PR can also receive that report as a sticky comment; a fork receives an inert log copy instead. Access and retention for summaries, logs, comments and optional artifacts are controlled by GitHub and the repository. The browser scanner is a separate scan and does not import Action history.
When telemetry is enabled, a coarse ten-field heartbeat sends action and detector versions, runner OS and architecture, repository visibility and a stable repository hash, aggregate grade and finding count, trigger, and whether delta was enabled. It sends no repository name, path, finding detail, commit SHA, branch name, user or token. Set telemetry: false to opt out.
Links in the report carry fixed campaign labels only. They do not include repository, path, branch, commit or finding data.
Limitations #
- Static checks do not execute submitted files or observe runtime behaviour.
- The action does not inspect model or provider behaviour, persisted memory, a running MCP server, or ordinary application code outside recognized roots.
- A grade describes supported files found in this run. It is not certification, a whole-repository security audit, or a guarantee of safety.
- Fork pull requests usually receive a read-only token, so their result falls back to the job log instead of a pull-request comment.
- delta scans the base as well as the head and therefore takes additional runner time.
Synthetic sample report #
This synthetic example mirrors the current report structure, but its paths, counts and findings are invented. It is not a real repository result, observed user outcome, adoption claim or pilot evidence.
SYNTHETIC EXAMPLE — structure only SkillTrust — 2 current issues SkillTrust check passes — report-only mode. Current: 1 new in this PR · 1 already on base Fixed by this PR: 1 Current base vs head, not previous runs. New in this PR (1) CRITICAL · SD-009 · skills/example/SKILL.md:18 Explanation: Downloads code and pipes it to a shell. Remediation: Download, verify, then execute separately. Already on base (1 · includes 1 HIGH) Details are collapsed in GitHub. Fixed by this PR (1) Present on base, absent from head. Grades for the current scan Security F · Permission hygiene A · Transparency B
Versioning #
Use @v1 to receive compatible v1 updates, or replace it with a full commit SHA when the workflow requires an immutable dependency.