CI Regress Kit

This kit keeps CI adoption "one PR to adopt" while preserving deterministic regress contracts.

Version note: this page is evergreen. Release-specific rollout notes belong in changelog and internal plan documents, not here.

One-PR Adoption Path (Default)

GitHub Actions is the primary lane:

• reusable workflow: .github/workflows/adoption-regress-template.yml
• step-level action: .github/actions/gait-regress/action.yml

Minimal adoption action:

1. Add the workflow to your repo.
2. Ensure fixture/config inputs are present (or keep deterministic fallback init enabled).
3. Open a PR and verify artifacts under gait-out/adoption_regress/.

Reusable Workflow Contract

The workflow supports:

• workflow_dispatch
• workflow_call

Inputs:

• fixture_runpack_path (default: fixtures/run_demo/runpack.zip)
• config_path (default: gait.yaml)
• source_run (default: run_demo, deterministic fallback fixture source)

Outputs:

• regress_status
• regress_exit_code
• top_failure_reason
• next_command
• artifact_root

Stable exit semantics:

• 0: pass
• 5: deterministic regression failure
• other: unexpected error passthrough

Deterministic artifact root:

• gait-out/adoption_regress/
  • regress_result.json
  • junit.xml
  • capture.json and regress_add_result.json (when using the explicit handoff path)
  • regress_init_result.json (only when legacy fallback init runs)
  • pack_verify_fixture.json (fixture integrity evidence)

Composite Action Contract

Use the action for step-level reuse:

- uses: ./.github/actions/gait-regress
  with:
    version: latest
    command: regress
    workdir: .
    upload_artifacts: true
    artifact_name: gait-regress-artifacts

Supported command values:

• regress
• policy-test

Action outputs:

• exit_code
• summary_path
• artifact_path

CI Portability Contract (GitLab/Jenkins/Circle)

Non-GitHub CI providers should call one compatibility contract script:

• scripts/ci_regress_contract.sh

Portable templates:

• GitLab: examples/ci/portability/gitlab/.gitlab-ci.yml
• Jenkins: examples/ci/portability/jenkins/Jenkinsfile
• CircleCI: examples/ci/portability/circleci/config.yml

Local parity check:

bash scripts/ci_regress_contract.sh

The portability templates are wrappers around this script and must preserve:

• identical regress exit handling (0, 5, passthrough)
• identical artifact root (gait-out/adoption_regress/)
• identical fixture fallback behavior (run_demo init path)

Explicit Capture vs One-Command Bootstrap

Use one of these two truthful paths:

1. Explicit handoff artifact:
   • gait capture --from --json
   • gait regress add --from ./gait-out/capture.json --json
   • gait regress run --json --junit
2. One-command bootstrap:
   • gait regress bootstrap --from --json --junit

Both paths preserve the same stable exit and artifact contract.

Pre-Commit and Pre-Push Hooks

The repo-local hook contract lives in .pre-commit-config.yaml.

Use:

pre-commit install
pre-commit run --all-files

Current hook coverage includes:

• standard hygiene checks
• Go formatting and module tidy
• golangci-lint
• Ruff and Ruff format for Python
• site-stack-lint on docs-site and ui/local/
• pre-push site-stack-build
• pre-push make prepush

Downstream Reuse Example

name: downstream-regress

on:
  pull_request:

jobs:
  regress:
    uses: ./.github/workflows/adoption-regress-template.yml
    with:
      fixture_runpack_path: fixtures/run_demo/runpack.zip
      config_path: gait.yaml
      source_run: run_demo

Path-Filtered PR Guidance

Require this lane for changes touching:

• cmd/gait/**
• core/runpack/**
• core/regress/**
• core/gate/**
• schemas/**
• docs/integration_checklist.md
• docs/ci_regress_kit.md
• .agents/skills/**

Validation commands:

bash scripts/test_ci_regress_template.sh
bash scripts/test_ci_portability_templates.sh

Frequently Asked Questions

How do I add Gait regression to CI?

Copy the template workflow (.github/workflows/adoption-regress-template.yml) or use the drop-in action (.github/actions/gait-regress/). Both produce JUnit output.

What does exit code 5 mean?

Exit 5 means regression failed — the current run drifted from the baseline fixture. Exit 0 means pass.

Can I use Gait with GitLab CI?

Yes. The CI regress kit provides portable templates for GitLab, Jenkins, and CircleCI that use the same CLI exit and artifact contract.

How do I create a regression fixture?

Run gait regress bootstrap --from --junit for the one-command path. If you want an explicit handoff artifact first, run gait capture --from --json and then gait regress add --from ./gait-out/capture.json --json.

Does regression testing require network access?

No. Regression testing is fully offline. It compares the current run against the baseline fixture using deterministic stubs.