CI quality gates (pre-merge checks)
Sets up the checks that gate a pull request before it merges to develop:
the toolchain provisioning, then lint + format-check + type-check + test, with
Jarvus's standard linters. The reusable core is the gate harness — provisioning,
the script contract, path filters, lockfile-frozen installs — and linting is one
tier that rides on it next to type-check and test.
The portfolio's actual failure mode isn't picking the wrong linter; it's repos
that ship no linter at all (tests + type-check only, or build + test only).
This skill exists so a new repo gets the whole gate by default instead of
re-deciding — or skipping it.
Scope: what's in, what's out
| In scope (gates a PR before merge) |
Out of scope (hand off) |
| asdf provisioning + tool caching |
Release-PR automation → release-flow |
| lint, format-check, type-check, test |
Container build / image publish → per-stack build docs |
IaC fmt + validate (credential-free) |
Deploy / tofu apply → sysadmin / deploy skill |
docs build --strict (optional) |
tofu plan & integration tests needing secrets (later gate) |
One-sentence charter: how a repo gates a PR before it merges. If credentials
or a release tag are involved, it's a different skill.
Know the hole this scope leaves: Dockerfiles. Image builds being
out-of-scope means a Dockerfile break passes every PR gate and first fails
after merge, on the push-triggered build workflow. Adopters should accept
that consciously — the fix, when it has bitten, is a docker-build smoke job in
the PR gate set (build, don't push; still credential-free), not moving
publish/deploy here. Where image builds are gated is the per-stack build
docs and deploy skills. (Frontend vite build is different — that one is
in-scope and cheap; see ui-checks.yml.)
Enforcement philosophy
Three decisions shape how everything below is wired:
1. CI is the only gate — no pre-commit. The gate lives in CI and nowhere else.
Pre-commit hooks are per-developer (must be installed, drift between machines, and
are one --no-verify from being skipped), add commit-time friction, and only ever
duplicate what CI already enforces authoritatively. So don't ship a
.pre-commit-config.yaml. Run each linter directly in CI — oxlint,
oxfmt --check, ruff check, sqlfluff lint --format github-annotation-native —
which keeps inline PR annotations without the framework. Local fast feedback comes
from the editor (oxc-vscode, ruff, a sqlfluff LSP) and from running the same
bun run <gate> / tool commands by hand — never a git hook.
2. Organize workflows by gate; co-locate by toolchain. The default lanes are
lint and test, each a workflow whose jobs fan out per package/language. But when
a domain brings a distinct toolchain, give it its own workflow whose jobs are
named by gate instead of forcing that toolchain into the generic lint/test
workflows. Terraform (tf-validate.yml: fmt + validate) is the first instance;
dbt is the second — its sqlfluff linter compiles models through dbt, so it
needs the same uv + dbt deps + profile setup as dbt parse/unit-tests.
Co-locating those in one dbt.yml (jobs lint / parse / unit-test) stands the
toolchain up once and keeps the gate semantics legible; splitting them across
lint.yml and test.yml would provision dbt twice. Rule of thumb: one workflow
per toolchain, jobs named by gate. Fold into the shared lint.yml/test.yml only
when a check rides the same toolchain those already set up.
3. Stack skills own their tools; this skill owns the harness. Each
jarvus-{tech} stack skill defines its tech's linter/formatter/test choices,
configs, and package.json/script contract, and carries a short "CI & Code Quality"
section pointing here. This skill owns provisioning, the gate taxonomy, the
path-filter / lockfile-frozen / credential-free rules, and the workflow templates. A
stack skill that introduces a distinct toolchain ships its domain workflow (its
lane of this contract) — e.g. jarvus-dbt ships dbt.yml. A new stack plugs
into these rules rather than reinventing CI.
The two reference deep-dives
| File |
Read when |
| provisioning.md |
the CI harness — asdf + cache composite, lockfile-frozen installs, path filters, credential-free principle, private-dep git rewrite |
| tool-standards.md |
the linters/formatters — the TS script contract, oxc + ruff configs, the typecheck naming convention, the editor-feedback loop (no pre-commit), the one-time adoption migration |
The gate set
| Gate |
TypeScript |
Python |
IaC |
| Lint |
oxlint |
ruff check |
— |
| Format |
oxfmt --check |
ruff format --check |
tofu fmt -check |
| Types |
tsc --noEmit |
mypy (optional) |
tofu validate -backend=false |
| Test |
bun test |
pytest |
— |
All four TS gates are invoked through a fixed script contract —
lint / format / format:check / typecheck — so the workflow is identical
across packages and only calls bun run <name>. Details + the naming caveat in
tool-standards.md.
DB-backed tests stay in this gate — they just need a database. A bun test /
pytest suite that hits Postgres is still fork-safe (no secrets), so it belongs
here: give CI an ephemeral service-container Postgres and an explicit
DATABASE_URL. Locally, that same test script gets an isolated DB from
agent-dev-workflow's bin/test + test preload, whose ??= defers to CI's
DATABASE_URL. (Integration tests that need secrets are the separate later gate
in the scope table above.)
The universal harness (don't reinvent it)
Every job, every language, shares the same provisioning. Consolidate it into one
local composite action and call it after checkout:
steps:
- uses: actions/checkout@v6
- uses: ./.github/actions/setup-asdf # asdf + cache + reshim, one place
Plus three rules that make CI reproducible and cheap (full rationale in
provisioning.md):
.tool-versions is the only place tool versions live — local dev and CI
read the same file, so they can't drift.
- Lockfiles committed; CI installs frozen —
bun install --frozen-lockfile,
uv run --frozen …. A PR can't pass against unrecorded dependency versions.
- Path-filtered triggers — each workflow fires only on its domain (and on
edits to itself).
- Leave
pull_request.branches unrestricted — filter PR triggers by
paths, never by base branch. In the develop→main Release-PR flow, the
release PR targets main; an unrestricted pull_request trigger re-runs the
full gate set on it alongside release-validate, re-gating exactly what's
about to ship. Adding branches: [develop] to pull_request silently
un-gates release PRs. (The push trigger does restrict to
branches: [develop] — that one's correct.)
- Credential-free — lint/format/type-check/validate/hermetic-tests need no
secrets, so they run on fork PRs and start instantly.
Templates
references/templates/ — copy and adapt (each carries # ADAPT: markers):
| Template |
Drop at |
Purpose |
github-actions/setup-asdf/action.yml |
.github/actions/setup-asdf/action.yml |
the shared provisioning composite |
github-actions/lint.yml |
.github/workflows/lint.yml |
ruff + oxc/tsc lint gate (per-package matrix) |
github-actions/test.yml |
.github/workflows/test.yml |
pytest + bun test gate |
github-actions/ui-checks.yml |
.github/workflows/ui-checks.yml |
single-package frontend lint+fmt+types+test+build |
github-actions/tf-validate.yml |
.github/workflows/tf-validate.yml |
OpenTofu fmt + validate |
github-actions/docs.yml |
.github/workflows/docs.yml |
mkdocs strict build gates PRs; Pages deploy on push only |
oxlintrc.base.json |
.oxlintrc.json (or root .oxlintrc.base.json in a monorepo) |
TS lint config — correctness=error |
oxlintrc.react.json |
<ui>/.oxlintrc.json |
stricter React/UI lint config |
ruff.pyproject.toml |
append to pyproject.toml |
ruff rule set |
vscode-extensions.json |
.vscode/extensions.json |
recommend oxc-vscode for local feedback |
Build order
- Read provisioning.md and
tool-standards.md first. They carry the
rationale and the gotchas (reshim-after-cache, the
typecheck naming convention).
- Confirm
.tool-versions exists and pins everything CI needs (bun, uv,
python, opentofu — whatever applies). If not, set it via asdf set … first.
- Drop the composite action at
.github/actions/setup-asdf/action.yml.
- Add per-language config + scripts: oxc configs + the four
package.json
scripts for TS; the ruff block + uv add --dev ruff for Python.
- Add the workflows you need, delete the jobs you don't, fix the
paths:
and working-directory: to the repo's real layout.
- For an existing repo, land the one-time format/lint-fix as a separate commit
before the workflow commit (see the migration section in
tool-standards.md) so the gate goes green on
its first run.
- Commit
.vscode/extensions.json so local editors match CI.
- Verify: open a PR (or push a branch) and confirm each gate runs, is
green, and a deliberate violation actually fails it. Don't assume — a
mis-filtered
paths: silently skips the gate, which reads as "passing".
Guardrails
- Don't let the gate need secrets. The moment a "lint" job wants cloud
credentials, it's the wrong job — split the credentialed check into its own
later workflow. Keep this set fork-safe and instant.
- One linter + one formatter per language. oxc for TS, ruff for Python. Don't
add eslint/prettier/biome/black alongside — that's the sprawl this replaces. A
Vite scaffold ships a default eslint; remove it when adopting oxc.
- Type-check is a gate, not a nicety.
tsc --noEmit / strict mode catches
bugs no linter does — keep it required.
- No pre-commit framework. CI is the only gate; run linters directly in CI (they
emit PR annotations natively). Local feedback is the editor + running the gate
commands by hand. Don't add a
.pre-commit-config.yaml — even on multi-linter
repos (ruff + sqlfluff + markdown), run each tool directly in CI or in the domain's
workflow. See the enforcement philosophy above and
tool-standards.md.
- Stay before the merge line. Release, build, publish, deploy, and
credentialed plans belong to other skills. If you're editing
release-prepare.yml or a deploy workflow, you're in the wrong skill.
1---2name: ci-quality-gates3description: >-4 Stand up the pre-merge CI quality gates a repo runs before code lands on develop — tool provisioning (asdf + .tool-versions + cache), lockfile-frozen installs, path-filtered GitHub Actions, and the lint / format:check / typecheck / test gate set with Jarvus's standard linters (oxlint + oxfmt for TypeScript, ruff for Python, tofu fmt/validate for IaC). Use when setting up CI for a new repo, adding a lint/format/type-check/test gate to an existing one, wiring GitHub Actions for code quality, choosing or standardizing linters/formatters, fixing CI that re-installs tools slowly, or noticing a repo runs tests but no linter. Scope stops at merge — Release-PR automation belongs to release-flow; build/publish/deploy to per-stack build + deploy skills. Triggers: "set up CI", "add linting/CI", "GitHub Actions checks", "oxlint", "oxfmt", "ruff", "format check", "type-check in CI", "quality gate", "lint isn't running in CI", "asdf in CI".5metadata:6 source: https://skillmd.com/skills/jarvusinnovations/ci-quality-gates7---89# CI quality gates (pre-merge checks)1011Sets up the checks that gate a pull request **before it merges to `develop`**:12the toolchain provisioning, then lint + format-check + type-check + test, with13Jarvus's standard linters. The reusable core is *the gate harness* — provisioning,14the script contract, path filters, lockfile-frozen installs — and linting is one15tier that rides on it next to type-check and test.1617The portfolio's actual failure mode isn't picking the wrong linter; it's repos18that ship **no linter at all** (tests + type-check only, or build + test only).19This skill exists so a new repo gets the whole gate by default instead of20re-deciding — or skipping it.2122## Scope: what's in, what's out2324| In scope (gates a PR before merge) | Out of scope (hand off) |25| --- | --- |26| asdf provisioning + tool caching | Release-PR automation → **`release-flow`** |27| lint, format-check, type-check, test | Container build / image publish → per-stack build docs |28| IaC `fmt` + `validate` (credential-free) | Deploy / `tofu apply` → **`sysadmin`** / deploy skill |29| docs `build --strict` (optional) | `tofu plan` & integration tests needing secrets (later gate) |3031One-sentence charter: **how a repo gates a PR before it merges.** If credentials32or a release tag are involved, it's a different skill.3334**Know the hole this scope leaves: Dockerfiles.** Image builds being35out-of-scope means a Dockerfile break passes every PR gate and first fails36*after* merge, on the push-triggered build workflow. Adopters should accept37that consciously — the fix, when it has bitten, is a docker-build smoke job in38the PR gate set (build, don't push; still credential-free), not moving39publish/deploy here. Where image builds *are* gated is the per-stack build40docs and deploy skills. (Frontend `vite build` is different — that one is41in-scope and cheap; see `ui-checks.yml`.)4243## Enforcement philosophy4445Three decisions shape how everything below is wired:4647**1. CI is the only gate — no pre-commit.** The gate lives in CI and nowhere else.48Pre-commit hooks are per-developer (must be installed, drift between machines, and49are one `--no-verify` from being skipped), add commit-time friction, and only ever50*duplicate* what CI already enforces authoritatively. So **don't ship a51`.pre-commit-config.yaml`.** Run each linter **directly** in CI — `oxlint`,52`oxfmt --check`, `ruff check`, `sqlfluff lint --format github-annotation-native` —53which keeps inline PR annotations without the framework. Local fast feedback comes54from the **editor** (oxc-vscode, ruff, a sqlfluff LSP) and from running the same55`bun run <gate>` / tool commands by hand — never a git hook.5657**2. Organize workflows by gate; co-locate by toolchain.** The default lanes are58`lint` and `test`, each a workflow whose jobs fan out per package/language. But when59a domain brings a **distinct toolchain**, give it its **own workflow whose jobs are60named by gate** instead of forcing that toolchain into the generic lint/test61workflows. Terraform (`tf-validate.yml`: `fmt` + `validate`) is the first instance;62**dbt** is the second — its `sqlfluff` linter compiles models *through dbt*, so it63needs the same `uv` + `dbt deps` + profile setup as `dbt parse`/unit-tests.64Co-locating those in one `dbt.yml` (jobs `lint` / `parse` / `unit-test`) stands the65toolchain up once and keeps the gate semantics legible; splitting them across66`lint.yml` and `test.yml` would provision dbt twice. **Rule of thumb: one workflow67per toolchain, jobs named by gate.** Fold into the shared `lint.yml`/`test.yml` only68when a check rides the *same* toolchain those already set up.6970**3. Stack skills own their tools; this skill owns the harness.** Each71`jarvus-{tech}` stack skill defines its tech's linter/formatter/test choices,72configs, and `package.json`/script contract, and carries a short "CI & Code Quality"73section pointing here. This skill owns provisioning, the gate taxonomy, the74path-filter / lockfile-frozen / credential-free rules, and the workflow templates. A75stack skill that introduces a distinct toolchain ships its **domain workflow** (its76lane of this contract) — e.g. **`jarvus-dbt`** ships `dbt.yml`. A new stack plugs77into these rules rather than reinventing CI.7879## The two reference deep-dives8081| File | Read when |82| --- | --- |83| [provisioning.md](references/provisioning.md) | the CI harness — asdf + cache composite, lockfile-frozen installs, path filters, credential-free principle, private-dep git rewrite |84| [tool-standards.md](references/tool-standards.md) | the linters/formatters — the TS script contract, oxc + ruff configs, the `typecheck` naming convention, the editor-feedback loop (no pre-commit), the one-time adoption migration |8586## The gate set8788| Gate | TypeScript | Python | IaC |89| --- | --- | --- | --- |90| Lint | `oxlint` | `ruff check` | — |91| Format | `oxfmt --check` | `ruff format --check` | `tofu fmt -check` |92| Types | `tsc --noEmit` | `mypy` (optional) | `tofu validate -backend=false` |93| Test | `bun test` | `pytest` | — |9495All four TS gates are invoked through a fixed **script contract** —96`lint` / `format` / `format:check` / `typecheck` — so the workflow is identical97across packages and only calls `bun run <name>`. Details + the naming caveat in98[tool-standards.md](references/tool-standards.md).99100**DB-backed tests stay in this gate — they just need a database.** A `bun test` /101`pytest` suite that hits Postgres is still fork-safe (no secrets), so it belongs102here: give CI an **ephemeral service-container Postgres** and an explicit103`DATABASE_URL`. Locally, that same `test` script gets an isolated DB from104**`agent-dev-workflow`**'s `bin/test` + test preload, whose `??=` defers to CI's105`DATABASE_URL`. (Integration tests that need *secrets* are the separate later gate106in the scope table above.)107108## The universal harness (don't reinvent it)109110Every job, every language, shares the same provisioning. Consolidate it into one111local composite action and call it after checkout:112113```yaml114steps:115 - uses: actions/checkout@v6116 - uses: ./.github/actions/setup-asdf # asdf + cache + reshim, one place117```118119Plus three rules that make CI reproducible and cheap (full rationale in120[provisioning.md](references/provisioning.md)):121122- **`.tool-versions` is the only place tool versions live** — local dev and CI123 read the same file, so they can't drift.124- **Lockfiles committed; CI installs frozen** — `bun install --frozen-lockfile`,125 `uv run --frozen …`. A PR can't pass against unrecorded dependency versions.126- **Path-filtered triggers** — each workflow fires only on its domain (and on127 edits to itself).128- **Leave `pull_request.branches` unrestricted** — filter PR triggers by129 `paths`, never by base branch. In the develop→main Release-PR flow, the130 release PR targets `main`; an unrestricted `pull_request` trigger re-runs the131 full gate set on it alongside release-validate, re-gating exactly what's132 about to ship. Adding `branches: [develop]` to `pull_request` silently133 un-gates release PRs. (The `push` trigger *does* restrict to134 `branches: [develop]` — that one's correct.)135- **Credential-free** — lint/format/type-check/validate/hermetic-tests need no136 secrets, so they run on fork PRs and start instantly.137138## Templates139140`references/templates/` — copy and adapt (each carries `# ADAPT:` markers):141142| Template | Drop at | Purpose |143| --- | --- | --- |144| `github-actions/setup-asdf/action.yml` | `.github/actions/setup-asdf/action.yml` | the shared provisioning composite |145| `github-actions/lint.yml` | `.github/workflows/lint.yml` | ruff + oxc/tsc lint gate (per-package matrix) |146| `github-actions/test.yml` | `.github/workflows/test.yml` | pytest + bun test gate |147| `github-actions/ui-checks.yml` | `.github/workflows/ui-checks.yml` | single-package frontend lint+fmt+types+test+build |148| `github-actions/tf-validate.yml` | `.github/workflows/tf-validate.yml` | OpenTofu fmt + validate |149| `github-actions/docs.yml` | `.github/workflows/docs.yml` | mkdocs strict build gates PRs; Pages deploy on push only |150| `oxlintrc.base.json` | `.oxlintrc.json` (or root `.oxlintrc.base.json` in a monorepo) | TS lint config — correctness=error |151| `oxlintrc.react.json` | `<ui>/.oxlintrc.json` | stricter React/UI lint config |152| `ruff.pyproject.toml` | append to `pyproject.toml` | ruff rule set |153| `vscode-extensions.json` | `.vscode/extensions.json` | recommend oxc-vscode for local feedback |154155## Build order1561571. **Read [provisioning.md](references/provisioning.md) and158 [tool-standards.md](references/tool-standards.md) first.** They carry the159 rationale and the gotchas (reshim-after-cache, the `typecheck` naming convention).1602. **Confirm `.tool-versions` exists** and pins everything CI needs (bun, uv,161 python, opentofu — whatever applies). If not, set it via `asdf set …` first.1623. **Drop the composite action** at `.github/actions/setup-asdf/action.yml`.1634. **Add per-language config + scripts:** oxc configs + the four `package.json`164 scripts for TS; the ruff block + `uv add --dev ruff` for Python.1655. **Add the workflows you need**, delete the jobs you don't, fix the `paths:`166 and `working-directory:` to the repo's real layout.1676. **For an existing repo, land the one-time format/lint-fix as a separate commit168 *before* the workflow commit** (see the migration section in169 [tool-standards.md](references/tool-standards.md)) so the gate goes green on170 its first run.1717. **Commit `.vscode/extensions.json`** so local editors match CI.1728. **Verify**: open a PR (or push a branch) and confirm each gate runs, is173 green, and a deliberate violation actually fails it. Don't assume — a174 mis-filtered `paths:` silently skips the gate, which reads as "passing".175176## Guardrails177178- **Don't let the gate need secrets.** The moment a "lint" job wants cloud179 credentials, it's the wrong job — split the credentialed check into its own180 later workflow. Keep this set fork-safe and instant.181- **One linter + one formatter per language.** oxc for TS, ruff for Python. Don't182 add eslint/prettier/biome/black alongside — that's the sprawl this replaces. A183 Vite scaffold ships a default eslint; remove it when adopting oxc.184- **Type-check is a gate, not a nicety.** `tsc --noEmit` / strict mode catches185 bugs no linter does — keep it required.186- **No pre-commit framework.** CI is the only gate; run linters directly in CI (they187 emit PR annotations natively). Local feedback is the editor + running the gate188 commands by hand. Don't add a `.pre-commit-config.yaml` — even on multi-linter189 repos (ruff + sqlfluff + markdown), run each tool directly in CI or in the domain's190 workflow. See the enforcement philosophy above and191 [tool-standards.md](references/tool-standards.md).192- **Stay before the merge line.** Release, build, publish, deploy, and193 credentialed plans belong to other skills. If you're editing194 `release-prepare.yml` or a deploy workflow, you're in the wrong skill.