IntegrateGuide 07
GitHub Actions
Run changed-file checks with annotations, summaries, and SARIF.
On this page
The official Action installs a verified quality release, checks pull-request changes, and writes native annotations and a job summary:
name: Quality
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
security-events: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
quality:
runs-on: macos-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: santi020k/quality@v2.1.0
id: quality
with:
version: v2.1.0
changed-only: true
report-level: warning
fail-level: warning
require-checks: true
jobs: 4
timeout-seconds: 120
- name: Upload code-scanning results
if: always() && steps.quality.outputs.sarif != ''
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: ${{ steps.quality.outputs.sarif }}
With Quality 2, omitting version installs the same CLI version as the pinned
Action. An explicit version must be an exact release, with or without the v prefix
(for example v2.1.0);
prerelease and build identifiers are supported. Use version: latest explicitly
to follow the latest release. Downloaded and cached exact-version binaries are
checked with quality --version before checks run.
Warnings fail by default; set fail-level: error only for an intentional,
documented migration period.
The Action exposes sarif, findings, tools, and duration-ms outputs. Set
sarif: "" to disable the public report; counts still come from a private report
in the runner’s temporary directory, removed after use. tools counts adapters
that actually ran, and duration is reported even if installation or execution
fails. On pull requests the Action compares against origin/$GITHUB_BASE_REF;
on pushes without a base it checks the complete project.
An unsuccessful check may reflect policy findings or analyzer failures. When
the CLI cannot complete, the Action retains its exit code and error context. require-checks
defaults to true; jobs, timeout-seconds, and max-output-bytes expose the
CLI’s execution limits.
Generate a standalone workflow
Generate a workflow with an explicit installation command:
quality ci github --install \
'cargo install --git https://github.com/your-org/quality --tag v2.1.0 --locked'
The generated workflow:
- Checks out complete Git history for change detection.
- Selects macOS for Swift repositories and Linux otherwise.
- Sets up the detected package manager and installs frozen dependencies.
- Sets up detected Rust, Java/Gradle, SwiftLint, SwiftFormat, and Actionlint requirements.
- Installs
qualityusing the command you supplied. - Runs
quality doctorto expose environment problems. - Checks pull-request changes against the base branch.
- Emits native GitHub annotations and uploads SARIF to code scanning.
Reuse pnpm CI
The repository also publishes a reusable pnpm workflow for build, test and browser jobs. Generate a compact caller with the CLI:
quality ci github \
--shared-ref '<reviewed-release-commit-sha>' \
--command 'pnpm run verify'
Or call .github/workflows/reusable-pnpm-ci.yml directly from a job. The workflow
reads the pnpm version from packageManager, installs frozen dependencies, runs a
trusted repository command and can install cached Playwright browsers or upload
failure diagnostics. Repositories without a packageManager declaration must pass
the workflow’s pnpm-version input; generated callers add a pinned fallback. Use a
caller matrix to shard browser jobs.
Deployment credentials, database migrations, environment approvals, tagging and
production smoke tests stay in the consuming repository. Deployment jobs can use
santi020k/quality/actions/setup-pnpm to remove repeated setup steps without moving
those safeguards into shared code. Package-release jobs can pass registry-url;
authentication tokens remain scoped to the consuming workflow’s environment.
Migrate an existing pnpm job
Replace separate pnpm, Node.js and frozen-install steps with the composite action. Keep repository-specific commands, conditions, matrices, credentials and deployment gates in the consuming workflow:
- uses: santi020k/quality/actions/setup-pnpm@eec1701b98bcc0b76d36af288ee78a0369cd84cc # v1.1.1
with:
node-version-file: .node-version
- run: pnpm run verify
For Turborepo or another local task runner, the next release also supports an opt-in task-output cache before the frozen install. The commit SHA in this example must be replaced with the reviewed release commit that contains these inputs:
- uses: santi020k/quality/actions/setup-pnpm@<reviewed-release-commit-sha>
with:
node-version-file: .node-version
task-cache-path: .turbo/cache
task-cache-key: quality
task-cache-config-path: turbo.json
The cache key isolates operating system, architecture, Node configuration, job
namespace, dependency and task-runner configuration, and commit. Exact commits can
save new entries while restore prefixes reuse valid task outputs from earlier runs.
Use a distinct task-cache-key for jobs or matrix shards that must not share
outputs. Leave task-cache-path empty to disable this cache. The action exposes
task-cache-hit for job summaries or diagnostics.
Publish to an authenticated package registry
Quality 1.1.1 added registry-url to the shared setup action. Pin the action to a
reviewed commit, configure the registry without a token, and expose the token only
to the publishing step:
- uses: santi020k/quality/actions/setup-pnpm@eec1701b98bcc0b76d36af288ee78a0369cd84cc # v1.1.1
with:
node-version: 24
registry-url: https://registry.npmjs.org
- name: Publish package
run: pnpm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
The setup action writes the registry configuration expected by actions/setup-node;
it does not read or own the credential. If dependency installation also requires a
private registry, provide NODE_AUTH_TOKEN to the setup action step so its built-in
frozen install can authenticate. Keep that secret in the consuming repository or
environment, and never pass it as an action input.
Cost-aware CI
Run JavaScript, Android, Kotlin, and Rust jobs on Linux whenever platform requirements permit. Reserve macOS runners for Swift and Xcode work.
Cancel obsolete pull-request runs when a newer commit arrives:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
For monorepos, combine the Action’s changed-only mode with Turborepo’s affected-package selection so unchanged applications never start expensive jobs.
Before pushing, use the repository’s configured local gate to catch deterministic failures without consuming a failed hosted run:
quality ci plan
quality ci local
The plan distinguishes exact local command coverage from steps that require GitHub-hosted actions, expressions, permissions, or services. Local success is early feedback; keep the protected GitHub check for the exact pushed commit.
Reporting and failure levels
Reporting and build policy are independent:
quality check --report-level warning --fail-level error
Warnings appear as annotations and in SARIF, while only errors fail the job. Required tools that are missing always fail regardless of severity settings.