# Local CI and PR gates

> Run reproducible pull-request checks before pushing and inspect the remaining GitHub-only boundary.

`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

```bash
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:

```yaml
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

```bash
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:

```yaml
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:

```yaml
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:

```bash
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:

```bash
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](/quality-ci-plan.schema.json),
[run-report schema](/quality-local-ci.schema.json),
[history schema](/quality-local-ci-history.schema.json), and
[comparison schema](/quality-local-ci-comparison.schema.json).

## 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`:

```text
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.
