Run heavy CI locally. Prove the exact commit on GitHub.
Commit CI Preflight (CCP) is an independent, vendor-neutral Apache-2.0 Rust project that turns expensive, deterministic checks into commit-bound evidence: run a reviewed plan on your machine, then let a small GitHub gate verify the exact pull-request head. It is for teams whose remote CI cost or queue time is growing without weakening review, security, or platform coverage.
Start here:
- PR #71 case study — a bounded, public example.
- Economic qualification — measured private-repository savings and limits.
- Clean-room tutorial — produce and verify a first receipt.
- Adoption guide — decide whether CCP fits your repository.
Status: v0.1.0-rc.1 prerelease. The source implementation and native benchmark evidence are complete. The GitHub prerelease distributes an unsigned macOS arm64 archive and checksum. No crate, Homebrew formula, Winget/Scoop package, container image, or signed artifact is published.
Running the same formatter, compiler, test suite, and documentation build on a powerful developer machine and again on paid hosted runners can be expensive and slow. Moving execution to a self-hosted runner removes one deployment model, but does not by itself give portable, independently checkable evidence.
Commit CI Preflight splits the work:
- the heavy, reproducible checks run locally in a pinned Linux container;
- a canonical receipt binds the exact Git commit, normalized configuration, image digest, commands, platform, and results;
- an independent Rust verifier applies repository policy;
- a small GitHub gate verifies the receipt against the exact pull-request head;
- review, permissions, trusted secrets, deployments, and uncovered native platforms remain remote.
The goal is not “zero CI”. The goal is to spend remote CI only where the remote control plane adds information or trust.
Local execution and receipt
flowchart LR
A["1 · Reviewed<br/>source commit"] --> B["2 · Local<br/>ccp run"]
B --> C["3 · Pinned Linux<br/>checks"]
C --> D["4 · Canonical<br/>receipt"]
Evidence and remote verification
flowchart LR
E["5 · Independent<br/>verification"] --> F["6 · Append-only<br/>evidence"]
F --> G["7 · Small<br/>GitHub gate"]
G --> H["8 · Exact-head<br/>status"]
The source checkout is read-only inside the container. Only declared cache and artifact paths are writable. Commands are explicit argv vectors, not an implicit shell. Receipts omit raw output, environment values, source contents, absolute home paths, and personal or machine identity fields.
A receipt is integrity and policy evidence. It is not an identity attestation, a signature, or proof that arbitrary local and hosted workflows are identical.
| If your repository has… | CCP fit |
|---|---|
| deterministic, container-friendly checks and pinned runtime images | Yes — start with a clean-room trial |
| trusted secrets, deployments, or platform-specific behavior | Partial — retain the relevant remote/native jobs |
| a requirement for signed identity-bound attestations | No — CCP is not that attestation system |
Adopting CCP in another repository? Start with the complete adoption guide. It covers what remains on GitHub, persistent cache setup, configuration and policy authoring, OrbStack or Docker-compatible execution, exact-commit receipts, the cross-repository gate, safe rollout, and rollback.
git clone https://github.com/MarcoPorcellato/commit-ci-preflight.git
cd commit-ci-preflight
cargo build --locked
./target/debug/commit-ci-preflight plan --config examples/projects/rust/.commit-ci-preflight.toml
./target/debug/commit-ci-preflight doctor --config examples/projects/rust/.commit-ci-preflight.toml
./target/debug/commit-ci-preflight dry-run --config examples/projects/rust/.commit-ci-preflight.tomlThe first build can take longer when Rust dependencies are not cached. plan
normalizes the contract, doctor performs a bounded runtime probe, and
dry-run renders the exact container command and mounts. None of these three
commands executes project code or emits an attestable receipt. For admission,
resource, cache, and guarded-workflow details, read the
coordination runbook,
local run contract, and
resource observation history.
The planned agent admission mode is an owner-approved safety exception for
orphan prevention, not a second scheduler. agent mode opt-in must remain
explicit: operators must never bypass unknown ownership, never revive a terminated chat,
and never auto-execute a command. An official launcher is a shell-free wrapper around one explicit program argv.
Official launchers must pass through guard exec to be covered. See the
coordination runbook, local run contract, and adoption guide above for the
complete safety contract.
For a real PASS and receipt, use the clean-room tutorial. It first creates a separate Git repository for the fixture; running the example configuration against this source checkout would validate the wrong repository.
Follow the end-to-end tutorial. It copies a tiny public Rust
fixture into its own Git repository, runs its test through a pinned container,
writes .ccp/receipt.json, and verifies that receipt against a
repository policy.
For installation, checksum verification, and local candidate archives, see the installation guide.
This public repository uses standard GitHub-hosted CI for ordinary pull requests. Linux and macOS execute the complete deterministic suite; Windows compiles every test target without executing runtime and cache paths whose native qualification remains pending. Public standard runners are free. Replacing those jobs with local execution produces no billable public-runner savings. It would consume maintainer time and Mac resources without an economic return, so the per-PR receipt requirement is retired here.
The historical CCP receipts remain valid evidence for their exact commits; they are not current pull-request gates. The PR #71 case study records the exact public anchors and limits. CCP can still qualify its own release candidates or bounded native behavior when a separate non-economic reason and exact authorization justify that work.
| Tool or approach | Primary model | Relationship to Commit CI Preflight |
|---|---|---|
| GitHub-hosted runners | GitHub provisions a remote VM and executes the workflow | Keep for remote identity, permissions, secrets, deployments, and platforms not covered by accepted local evidence |
| GitHub self-hosted runners | A machine you manage stays connected to GitHub and accepts GitHub-dispatched jobs | Commit CI Preflight runs before push without registering a long-lived runner; GitHub receives a minimized receipt |
act |
Reads GitHub Actions workflows and uses Docker to run actions locally | Commit CI Preflight intentionally does not execute marketplace actions; its importer emits an inert translated/manual/unsupported report and execution uses a smaller explicit config |
| Dagger | Programmable delivery engine with pipelines in code, content-addressed caching, services, and tracing | Commit CI Preflight is not a pipeline SDK or orchestration platform; it focuses on bounded local checks, canonical evidence, and a small remote policy gate |
| Earthly | Repeatable containerized builds described by Earthfiles | Commit CI Preflight does not introduce a build language; it wraps existing commands and focuses on receipt verification. Earthly's official documentation currently states that the project is no longer actively maintained |
| Commit CI Preflight | Explicit local check plan plus commit-bound receipt and independent policy verification | Optimizes the local/remote trust split rather than trying to reproduce every CI feature |
Official project descriptions used for this comparison:
- GitHub self-hosted runners
- GitHub-hosted runners
- nektos/act
- Dagger documentation
- Earthly documentation
- GitHub Actions pricing
These projects solve overlapping but different problems. Commit CI Preflight does not claim feature superiority or full GitHub Actions parity.
CCP produces no billable runner saving when it replaces standard hosted CI in a public repository. In a private repository it can preserve included quota and avoid billed compute, but only when the same required checks move off the hosted runners and the retained receipt gate remains cheaper.
Measured August 2026 examples:
| Case | Observed result |
|---|---|
| This public repository | $0 billable saving from replacing ordinary standard hosted PR jobs; hosted CI remains the default |
| Matryca-Knowledge | 28 rounded runner-minutes avoided across 30 gate events, approximately 46.7% of the former minimum and $0.168 at the billed Linux rate |
| Matryca-Brain | 22 CCP-guarded local attempts correspond to an estimated 635.1 hosted Linux minutes and $3.81 of GitHub compute avoided |
These are bounded observations, not a universal savings promise. The detailed inputs, arithmetic, privacy boundary, and limits are in Economic qualification and measured savings.
Pricing and quotas vary by account and date, so treat the formula below as a planning aid and replace every input with current measurements.
Remote bill estimate (assumption):
cost_remote = Σ(job_rounded_minutes × job_runner_rate) - applicable_included_credit
Local split estimate (assumption):
cost_local = local_runtime_minutes × chosen_local_cost_per_minute + remote_gate_cost
Estimated savings (assumption):
savings = previous_remote_cost - new_local_and_remote_cost
Positive savings favors the split under those assumptions; zero or negative
savings does not. Included quota, per-job rounding, retained remote jobs,
electricity, hardware amortization, and operator time can materially change the
result.
Use your current GitHub billing inputs and measured local runtime to replace the assumptions before deciding.
Use the beta candidate when:
- expensive or slow checks are deterministic and container-friendly;
- developers have capable local hardware;
- the repository can pin its runtime image by digest;
- project checks need only declared writable cache or artifact paths;
- maintainers can review a small explicit TOML plan;
- GitHub should retain the control-plane checks that only GitHub can know.
- Teams that can tolerate local compute for deterministic heavy checks.
- Repositories with stable Linux-based test/lint pipelines and clean host runtime.
- Maintainers who prefer explicit trust boundaries in reviews and policies.
A strong initial fit is a private repository with large Rust, Python, Node, or documentation checks that already run consistently in Linux containers.
- Workflow design that depends on unreviewed code from hostile contributors.
- Windows/macOS/GPU-specific execution without native project receipt evidence.
- Teams requiring organization-wide identity attestation for every green signal.
Do not use the beta as the sole gate when:
- checks require trusted cloud secrets, deployments, or private infrastructure;
- unreviewed code must be treated as actively hostile;
- macOS, Windows, GPU, or hardware-specific behavior lacks native evidence;
- the workflow depends on arbitrary marketplace actions or complex GitHub expression semantics;
- the organization requires signed identity-bound attestations;
- repository policy cannot safely accept locally produced evidence.
In those cases, retain the relevant remote or native jobs. Cost reduction never overrides a missing trust fact.
Current evidence guarantees are:
- A0 integrity and repository-policy assertion for receipts are published.
- A0 does not claim who ran the command, truthful remote-equivalent execution, or complete host trust.
- A1 and higher assurance levels are separate work items and are not inferred by current status.
commit-ci-preflight plan
commit-ci-preflight doctor
commit-ci-preflight dry-run
commit-ci-preflight run
commit-ci-preflight verify
commit-ci-preflight cache path|init|inventory|cleanup
commit-ci-preflight recover status --json
commit-ci-preflight recover apply <run-id> --json
commit-ci-preflight migrate-github-actions
commit-ci-preflight benchmark
commit-ci-preflight verify-benchmark
Key boundaries:
runrequires a clean Git commit and writes a canonical receipt;verifyseparates integrity, policy, and identity assurance;- cache cleanup is preview-only in 0.1.0;
recover statusis read-only and path-free;recover applyaccepts one exact 64-character run identifier and only quarantines CCP-owned journal state;migrate-github-actionsparses YAML as untrusted data and does not execute marketplace actions, expressions, commands, or secrets;guard execis a shell-free wrapper around one explicit program argv and inherits the caller environment without serializing it;- benchmark timing is observational and never affects the pinned correctness digest.
The fixed benchmark contract produced the same correctness digest on:
- native macOS arm64, with a separate OrbStack capability probe;
- native Linux x86_64 on
ubuntu-24.04; - native Windows x86_64 on
windows-2025.
Receipts, exact run metadata, hashes, and claim boundaries are in the PR09 evidence matrix.
This proves the fixed benchmark contract, not complete runtime qualification on
every platform. The complete repository preflight is currently qualified on
macOS arm64 through OrbStack. Linux and Windows complete run paths remain
pending. See the beta support matrix.
Read the threat model before enforcing receipts. Important non-claims:
- containers are not a complete sandbox against hostile code;
- SHA-256 integrity does not prove producer identity;
- checksums are not signatures;
- cache contents are not attestation evidence;
- a local PASS does not replace GitHub review, branch policy, or trusted deployment controls.
Report vulnerabilities privately as described in SECURITY.md.
-
Multi-runtime receipts v2 — one exact-head local receipt for independently pinned compatibility runtimes.
Issues and narrowly scoped pull requests are welcome. Read CONTRIBUTING.md, preserve the fail-closed claim boundaries, and never include secrets, proprietary fixtures, or personal data.
Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
Copyright 2026 Marco Porcellato.
Apache-2.0 section 4(d) governs preservation of the attribution notice in
redistributions that include a NOTICE file. The license does not require
advertising endorsement and does not grant trademark rights.