Run your CI on your laptop, before you push.

CI Kit gives a repository a local gate that mirrors what the GitHub Actions workflows do: the same installs, the same linters, the same type checks, the same tests. It also runs the workflows themselves locally through act, so the YAML can be checked without waiting for a runner.

1 copyof the setup โ€” the local run and the runner share it
0 driftbetween what runs locally and what runs in CI
Any stackthe gates are driven by what the repository contains
~100 sfor the gate to run on your own machine

The evidence

Every number is measured, and the evidence document says how each one was taken.

The clearest case came from the workspace this tool was built in. On one morning, twenty-eight of the last thirty CI runs on the largest repository had failed โ€” and not one of them failed on code. GitHub had refused to start the jobs:

The job was not started because recent account payments have failed
or your spending limit needs to be increased.

Every commit since had gone unverified, and the signal looked exactly like a red build. A local gate gives the same answer for free, in about a hundred seconds, and says plainly that the job never ran.

The same local gate found a secret-scan allowlist entry that no longer matched its file, ninety-three dependency advisories โ€” eight of them critical โ€” and build artefacts tripping a working-tree scan.

And it is not faster than a CI runner. Measured on the same work, the local gate took 99 s on a 2022 Intel laptop against 43โ€“48 s on a GitHub runner. A runner has more cores and faster storage. The local gate buys a guarantee of feedback, not a speed-up.

Why

CI feedback is slow, and it is slow at the worst moment: after you have already pushed.

A gate that runs in about a hundred seconds on your machine turns a five-minute round trip into a coffee break, and it catches the class of failure that CI is worst at โ€” the one that only happens on a fresh clone.

The hard part is not running the commands. It is keeping the local run and the CI run from drifting apart. That is what this kit is for: the setup steps live in the repository, in scripts/ci/, and both the Makefile and the workflow call them.

How it works

   developer                repository                    runner
      |                        |                             |
      |   make ci              |                             |
      |----------------------->|                             |
      |                        |  scripts/ci/*.sh            |
      |                        |  the setup and the gates    |
      |                        |         |                   |
      |                        |         +------------------->|  .github/workflows
      |                        |             the same script |
      |                        |                             |
      |   the same script, so the local run and the runner  |
      |   cannot disagree about what the code needs         |

There is one copy of the setup. It cannot disagree with itself.

Derived, not guessed

A stack runs the gates it declares. If a project has no lint step, the kit does not invent one.

The repository owns its setup

Anything a workflow and a laptop both need belongs in the repository, not in the kit.

Nothing is written outside the repository

No files, no hooks, no settings โ€” unless the command says so.

Install

curl -fsSL https://raw.githubusercontent.com/omeiza-workspace/ci-kit/main/bin/install.sh | sh

That puts the kit in ~/.local/share/ci-kit and links ci into ~/.local/bin. From a clone:

git clone https://github.com/omeiza-workspace/ci-kit.git ~/.local/share/ci-kit
ln -s ~/.local/share/ci-kit/bin/ci ~/.local/bin/ci

Homebrew:

brew tap omeiza-workspace/tap && brew install ci-kit

Use it

make            # list the targets
make ci         # the full local gate
make ci-fast    # lint and type checks only
make doctor     # is my toolchain the same as the one CI pins?
make act W=ci.yml J=test

With the mock services

API Mock Services is the mock engine the gates can point at โ€” the payment gateways, the identity checks, the email, the DNS, the messaging, the AI and the storage, offline and with no dependencies. Configure it in .ci/ci.json, and the kit starts the mocks when you ask it to, waits for them to answer, and tells you which one is missing if they are not.

make mocks-up      # start the mocks the tests need
make mocks-status  # are they answering?
make mocks-down    # stop them

The gate checks the mocks rather than starting them. A gate that quietly starts services hides the reason a test failed.

Read more

The evidence โ€” every measurement, how it was taken, and what is not claimed.
The architecture โ€” why it is shaped this way, and what it costs.
The README โ€” the whole thing, in a terminal.

Support the project

CI Kit is maintained in the open, and that takes time. If it has saved you the commit, push, wait, fail loop, or given your team back an hour a week of runner minutes, consider sponsoring the maintenance.

There is no paid tier and nothing is gated: the kit stays MIT, and every feature in it stays free.