IntegrateGuide 08
Local CI and PR gates
Run reproducible pull-request checks before pushing and inspect the remaining GitHub-only boundary.
On this page
quality can run a repository’s version-controlled Git hook as a timed local CI
gate. This catches deterministic failures before a push consumes a hosted
runner, while GitHub Actions remains authoritative for the exact pushed commit.
Inspect coverage
quality ci plan
quality ci plan --strict
quality ci plan --hook pre-commit --format json
The default plan compares pull-request workflows with hooks.pre-push in
quality.yml. Each workflow step is classified as:
- covered when its normalized
run:command and working directory exactly match a local hook step; - GitHub-only when it uses an action, expression, or conditional that needs GitHub context;
- uncovered when it is a plain command that could run locally but is absent from the selected hook.
The comparison is deliberately exact. It does not claim that a broad wrapper script covers a different workflow command, because doing so would turn an inference into false parity. Declare the relationship explicitly when a broader local wrapper genuinely includes the CI command:
hooks:
pre-push:
steps:
- name: Run full local validation
command: pnpm
args: [run, pre-push]
covers:
- pnpm run ci
covers affects the plan only; execution still runs the declared hook command.
Use --strict in adoption checks to reject uncovered commands.
Workflow- and job-level defaults.run.working-directory values are resolved
before comparison. A declared env or custom shell is not silently treated
as equivalent to a local hook: static context is uncovered, while expressions
that require GitHub context remain GitHub-only.
Jobs pinned to a different runner operating system are also GitHub-only; a
matching command on macOS does not claim coverage for Windows or Linux.
Run the gate
quality ci local
quality ci local --hook pre-commit
quality ci local --step 2
Steps run sequentially and stop after the first failure. The terminal report
shows each step’s wall time, the total wall time, the exit code and a concise
tail of bounded failure output, followed by normalized diagnostics and a focused rerun command. --step
accepts a one-based number from the plan or prior report. When a step forwards
Git hook arguments, the rerun uses a <git-hook-args> placeholder instead of
persisting values such as remote URLs; replace it with the original hook
arguments.
Hook steps default to the generic path:line[:column] parser. Select a
structured parser when the command emits that format:
hooks:
pre-push:
steps:
- name: Lint source
command: pnpm
args: [exec, eslint, ., --format, json, --max-warnings=0]
parser: eslint-json
Failed reports then include normalized file, line, column, severity, message, and rule fields. Structured parsers read standard output independently of standard error, so a tool warning cannot corrupt a JSON report. Successful hook output is never treated as a diagnostic.
Managed Git hooks use this same execution and reporting path. A typical policy
keeps pre-commit limited to staged-file checks and uses pre-push for affected
tests and builds:
hooks:
pre-commit:
steps:
- name: Check staged files
command: pnpm
args: [exec, lint-staged]
pre-push:
steps:
- name: Run affected validation
command: pnpm
args: [run, pre-push]
When a root package already declares pre-commit, precommit, pre-push, or
prepush, quality init and language-aware presets import that script as the
corresponding hook. Existing hook configuration is preserved.
Reports and privacy
The 20 most recent runs of each hook store metadata without command output
under the Git directory at quality/local-ci/ (per-worktree in a linked
worktree). Frequent commit-message checks cannot evict pre-push history. The
history stays outside the worktree and cannot be committed accidentally. A history write failure emits a warning but
does not change the gate result. Disable history with --no-history.
Inspect timing and status without retaining command output or diagnostics:
quality ci history --hook pre-push
quality ci show latest --hook pre-push
quality ci compare --hook pre-push
quality ci compare run-1790000000000 latest --format json
compare defaults to the latest run and the preceding run of the same hook
with the same executed step identities. It reports total and per-step duration
changes. A skipped step has no duration delta; an explicit base can compare
different workloads. Selectors accept latest, previous, a millisecond
timestamp, a run-<timestamp> ID, or its run-<timestamp>-<sequence> collision form.
previous selects the second-newest retained run after applying the hook filter.
Concurrent runs receive distinct IDs even when they start in the same millisecond.
Use the full ID from history to select a particular run. When you select an older
head without an explicit base, comparison uses the preceding comparable run.
Write a complete versioned report explicitly when another local tool needs the captured output:
quality ci local --format json --report reports/local-ci.json
Combined output retention defaults to 1 MiB per step and can be changed with
--max-output-bytes. Explicit reports may contain anything printed by a check;
do not commit or share them when a command may expose sensitive information.
The contracts are published as the plan schema,
run-report schema,
history schema, and
comparison schema.
Pin the project CLI
Quality 2 and newer enforce .quality-version in the selected project root
(the directory passed to --root, or the current directory). Write a released
version without a leading v:
2.0.0
Every project command checks this optional file before loading configuration.
On macOS and Linux, a mismatch fails with the exact checksum-verified installer
command; Windows receives the matching release and checksum location. Managed
hooks use this check when they invoke Quality 2 or newer. Older binaries do not
enforce the pin; install the required release before relying on it. A pin in a
parent repository does not apply automatically to a different --root.
What remains in GitHub
Local CI does not emulate hosted runner images or execute arbitrary uses:
actions. Secrets, GitHub permissions, service containers, CodeQL and dependency
review services, deployment, release publication, and platform-specific hosted
checks remain GitHub-only. Keep one protected GitHub check for the exact pushed
commit even after the local gate passes.