prepush-ci-setup
Skill10 starsChanged 36 days agoMITView on GitHub
Set up prepush-ci in a repository so that Claude Code cloud sessions run the full CI check in the pre-push hook and pull request CI skips commits that passed it. Use when the user asks to set up prepush-ci, to "run CI in the session", to "save CI minutes with cloud sessions", or to make pull request CI skip checked commits. Not for changing what the CI checks.
- Commits and pushes
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 5 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
If .prepush-ci.toml already exists, run uvx prepush-ci doctor, report its findings, and fix only what it lists.
- Very specific: line 20
Read every CI definition in the repository (.github/workflows/, .gitlab-ci.yml, .circleci/, Jenkinsfile, azure-pipelines.yml, …
- Very specific: line 21
Look for an entry point that already runs them: make ci, bin/ci, npm run ci, just ci, scripts/ci, a tox/nox session.
- Very specific: line 22
If there is none, or it misses CI steps, write scripts/ci: a POSIX sh script with set -eu that runs the steps in CI's order.
- Very specific: line 38
Check what the cloud container offers (command -v psql pg_ctlcluster redis-server docker, installed versions).
- Distinctive: line 40
If a service cannot run in the container at all, tell the user: the full check cannot replace CI for that part, and either that step stays …
- Distinctive: line 44
Before you change anything, list what the repository already has and tell the user what you found:
- Very specific: line 50
If there is more than one manager, ask the user which one to use and pass the choice as --hooks.
- Very specific: line 61
Cloud sessions only: run init with --hooks none.
- Very specific: line 68
Run init once, with the check from step 1, the preflight from step 2 and the answer from step 4:
- Very specific: line 77
after a yes, <check command> is the confirmed command line with the added options, or scripts/ci, unchanged, when the options are in the …
- Very specific: line 80
add --preflight "<command>" or --require-env <NAME> from step 2.
- Distinctive: line 93
Keep it idempotent and well within the hook timeout.
- Very specific: line 97
Add the gate for pull/merge request pipelines only.
- Very specific: line 101
Other systems: call prepush-ci verify "$SHA" first and exit early with success when it returns 0.
- Distinctive: line 107
Add a short section to CLAUDE.md (or AGENTS.md, whichever the repository uses):
- Very specific: line 111
Never use --no-verify. To push session commits from a machine that cannot run the full check, run prepush-ci strip <base>.
- Very specific: line 148
Run .claude/hooks/session-start.sh by hand (with CLAUDE_CODE_REMOTE=true and CLAUDE_ENV_FILE set) and source the exported variables into …
- Very specific: line 149
Run prepush-ci doctor --mode full.
- Distinctive: line 150
Commit the setup on the branch.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Set up prepush-ci
Goal: after this setup, every commit made in a cloud session carries the trailer Prepush-CI: full, the pre-push hook runs the full check before such a commit can leave the machine, and the pull request CI skips commits that carry it. The default branch keeps running CI in full.
Work on a branch and open a pull request with the result; do not push to the default branch. Make no assumption about the CI system: read what the repository has. Ask the user only where this skill says so.
0. Preconditions
- The repository is a git repository with a remote, and you can push branches.
prepush-ciis reachable:uvx prepush-ci --version(orpipx run prepush-ci --version). If the network policy blocks the package index, stop and tell the user which host is needed. Useuvxfor the commands you run yourself, once; hooks and the SessionStart script never use it (below).- If
.prepush-ci.tomlalready exists, runuvx prepush-ci doctor, report its findings, and fix only what it lists.
1. Find the full check
- Read every CI definition in the repository (
.github/workflows/,.gitlab-ci.yml,.circleci/,Jenkinsfile,azure-pipelines.yml,bitbucket-pipelines.yml,.buildkite/, others). List the commands that run on pull requests: tests, linters, format checks, type checks, builds, other validations. Ignore deploy, release and publishing steps. - Look for an entry point that already runs them:
make ci,bin/ci,npm run ci,just ci,scripts/ci, atox/noxsession. - If there is none, or it misses CI steps, write
scripts/ci: a POSIX sh script withset -euthat runs the steps in CI's order. Keep it free of CI-only setup (checkout, caching, service containers). - Ask the user to confirm the command and the list of steps it covers, naming any CI step you left out and why. Do not continue without a confirmed check.
- Propose (in the same pull request) that CI calls the same entry point, so the pre-push and CI cannot drift. If the user declines, note the drift risk in the docs.
- Have the check write its result files. The comment that step 8 and step 9 put on the pull request shows test counts and coverage only from files the check wrote. After the check is confirmed and before
initruns (step 5), have the check write a JUnit XML file to.prepush-ci/junit.xmland the coverage report of coverage.py as JSON to.prepush-ci/coverage.json, both at the top of the worktree, each only where the rules below allow it.- Where the files come from. Write the JUnit file for
pytestonly, through its own option (pytest --junitxml=.prepush-ci/junit.xml -o junit_family=xunit1), which adds the file and takes nothing from the console output; use an option the runner has built in, and never add a package or plugin to the project. Avitest,jestornode --testcheck gets no JUnit file, and you tell the user that the comment will show no counts for that check: a reporter named for the file (--reporter=junit,--reporters=jest-junit) replaces the reporters that the runner chooses itself from the environment (an agent reporter under an agent,github-actionsin GitHub Actions) and the project's ownreporters, so the console output of the check would change in the pre-push hook and in CI, and a list of reporters that equals what the runner would choose in every environment cannot be written;node --testhas a further problem, since its reporter destination does not create.prepush-ci/, so on a fresh checkout the run fails with exit 7 and the check turns red. The coverage file is the JSON of coverage.py (--cov-report=json:.prepush-ci/coverage.jsonbeside the--covthe check already has), and you write it only when the check already measures coverage with coverage.py: never add measurement, because a coverage threshold in the project's configuration would then start to fail the check; a runner that cannot write it gets a JUnit file and no coverage file. - Where the options go. Only into a check you can show. If the check is a command line, such as a runner call or a chain of commands, add the options to the test command in that line. If it is a
scripts/ciyou wrote in this run (item 3), add the options to the line of the script that runs the tests. For any other entry point (make ci,npm run ci,just ci, atoxornoxsession, or a script that existed before this run), write neither file, change no file of the project, and tell the user that the entry point is the project's and the comment will show no counts. - Only after a direct call of the runner. The options go to a test command that is a call of
pytest:pytestoruv run pytest. When the test command is itself an entry point, as inruff check . && make test,npm run lint && npm test, or ascripts/ciwhose test line istox -e py, write neither file, change no file of the project, and tell the user that the test command is not a call of the runner and the comment will show no counts; never append--junitxml,--reporter,--outputFile,--test-reporter-destination,JEST_JUNIT_OUTPUT_FILEor--cov-reportto a Makefile target, a package script or a tox session. - Only where the test command starts at the top of the worktree. The paths of the options are relative to the directory the test command starts in, so a file would land in another directory than the one step 8 looks in. When a command changes the directory before the test command starts (a
cdorpushdin the chain or the script,uv run --directory,make -C), as incd backend && pytest -qor ascripts/ciwhose test line follows acd, write neither file, change no file of the project, and tell the user that the test command runs in another directory and the comment will show no counts. The rule is about the directory in which the test command starts: in(cd web && npm run build) && pytest -qthecdended in a subshell beforepyteststarted, so the options go topytesthere. - One test command. The files make sense for one test command only: when the check runs tests with more than one command, neither file is written, because the commands would overwrite each other's files and the comment would show part of the tests as the whole; tell the user that the comment will show no counts for that reason.
- Leave the check's own output alone. The options add files and take nothing away. When the check names
--covand no--cov-report, on its command line or in the runner's configuration (addoptsofpytest.ini,pyproject.toml,tox.iniorsetup.cfg), add--cov-report=termbeside the JSON report: the JSON report alone replaces the table of uncovered lines that pytest-cov prints by default. When the command line or the runner's configuration already writes a JUnit file (--junitxmlinaddopts) or a coverage JSON file (--cov-report=json), do not add yours, because the later option wins and the check would stop writing the project's file; leave that file out and tell the user that the check already writes its own file and the comment will show no counts for it. - Tell the user, and ask. Before you change anything, show the user the change (the command line with the added options, or the changed line of
scripts/ci) and ask for a yes before you make it; leave the check as it is without the yes. The change is small: the change only adds the files and never changes the steps, the selection of tests or the thresholds of the check. For each file left out, for this or any other reason, tell the user which file is left out and why, and leave--junitor--coverageout of the step 8 call for it. Without the yes the files count as not written, and the step 8 call has neither--junitnor--coverage. - The ignore line. Where a file is written, add
.prepush-ci/to.gitignoreunless it is ignored already, because the pre-push hook refuses a worktree with untracked files that are not ignored. Do this only when at least one of the files is written; in every case where none is written (a "no", several test commands, an entry point, a test command that is not a runner call, a test command that runs in another directory), leave.gitignoreas it is.
- Where the files come from. Write the JUnit file for
2. Services and preflight
- List what CI provides besides the code: service containers (PostgreSQL, MySQL, Redis, …), environment variables, secrets used by tests.
- Check what the cloud container offers (
command -v psql pg_ctlcluster redis-server docker, installed versions). A different major version is acceptable; say so in the docs. - Write the preflight: list required variables for
--require-env <NAME>(once per variable), or writescripts/ci-preflightthat exits non-zero when a service is unreachable and pass it as--preflight "<command>". A missing service must fail the full check, never skip tests. A suite that skips its database tests while the commit carries the trailer makes the pull request CI skip unchecked code. - If a service cannot run in the container at all, tell the user: the full check cannot replace CI for that part, and either that step stays in pull request CI (not skipped) or the setup stops here.
3. Look at the existing hooks
Before you change anything, list what the repository already has and tell the user what you found:
git config core.hooksPath, and the effective hooks directory (git rev-parse --git-path hooks);- the files
commit-msgandpre-pushin that directory; - the files of the hook managers:
.pre-commit-config.yaml,.husky/,lefthook.yml.
If there is more than one manager, ask the user which one to use and pass the choice as --hooks. Without a manager the value is native.
4. Ask what pre-push should do locally
Stop and ask the user: "What should happen with pre-push on your own machines? (1) keep the existing hooks and run ours after them; (2) install the hooks only in cloud sessions; (3) fold the existing pre-push steps into the full check and remove the old hook." Wait for the answer before you run any command that installs hooks: init installs them at once, so the question comes first, never after.
- Keep the existing hooks (the default): run
initwith the--hooksvalue you found (step 5).- Native hooks:
initchains the existing hooks, which run first; leave the existing hook files as they are, never edit, move or removecommit-msgorpre-pushin the hooks directory. - pre-commit: the only changes to
.pre-commit-config.yamlare the blockinitwrites and the keysdefault_install_hook_typesanddefault_stages, every other line stays as it is. Commit these changes together with.prepush-ci.toml: committed, the session'sinstallfinds nothing to change. - With pre-commit the hooks set
verbose: true, and pre-commit then prints the whole output of the check on every push that runs it. In an agent session that output fills the context. Tell the user, and offer a check command that prints a summary and writes the detail to a file, or a quiet mode of the test runner such aspytest -q; change the check only with their yes. A quiet mode does not always help:node --testprints at least a line per test (up to Node 22, TAP when its output is not a terminal, as in an agent session). Keepverbose: true:doctorfails without it andinstallwrites it back. In an agent session cut the push's own output instead,git push 2>&1 | tail -n 40; the post-push hook recognizes that form. - husky or lefthook: the only change to the files under
.husky/or tolefthook.ymlis the blockinitwrites (a new hook file also starts with#!/usr/bin/env sh), every other line stays as it is. Commit the block together with.prepush-ci.toml.
- Native hooks:
- Cloud sessions only: run
initwith--hooks none. It applies when no hook manager is in use: the hooks then exist only where the SessionStart script installs them. - Fold into the check: the tool cannot do this by itself. Show the user the hook file, move its steps into the check command first, and remove the file only after the user confirms it by name. Without that yes, change no hook file.
With a hook manager only the first and the third answer are offered; say so and why: the session's install would modify the tracked config and leave the worktree dirty, so that every push refuses, while committing the block gives commit-msg and pre-push hooks to every developer who runs the manager's install, and they fail where the tool is missing.
5. Run init
Run init once, with the check from step 1, the preflight from step 2 and the answer from step 4:
uvx prepush-ci init --non-interactive \
--check "<check command>" \
--hooks <hooks> \
--default-branch "<default branch>"- after a yes,
<check command>is the confirmed command line with the added options, orscripts/ci, unchanged, when the options are in the script; without a yes<check command>is the confirmed check unchanged; <hooks>ispre-commit,husky,lefthookornativefor answers 1 and 3,nonefor answer 2;<default branch>comes from two commands, run in this order:git remote set-head origin --auto, which refreshes the local record from the remote, thengit symbolic-ref refs/remotes/origin/HEAD; remove the leadingrefs/remotes/origin/from the output of the second (refs/remotes/origin/release/1givesrelease/1). The commands fail whenorigindoes not exist, cannot be reached, has no default branch, or the clone does not fetch it (a single-branch clone of another branch); then ask the user for the default branch and do not guess it, and do not use the output of the second when the first failed;- add
--preflight "<command>"or--require-env <NAME>from step 2;--require-up-to-datestays at its default unless the user objects;--ci github|gitlab|generic|nonepicks the gate snippet it prints (default: detected).
init writes .prepush-ci.toml, installs the hooks, writes the SessionStart script and registers it, and prints the CI gate snippet; do not write those files by hand. If the repository already has legacy trailers from a hand-made version of this setup, add them to legacy_keys in .prepush-ci.toml. For pre-commit, check that no args: duplicate the check command (the config file is the single source of truth).
6. Extend the SessionStart script
init wrote .claude/hooks/session-start.sh. Extend that script with what the repository needs to run its check, after the prepush-ci install line; do not write another. It already returns immediately unless CLAUDE_CODE_REMOTE is true, installs the tool with uv tool install, installs the hooks and exports PREPUSH_CI=full and PATH through $CLAUDE_ENV_FILE. Add:
- dependencies from the lockfile (
uv sync --frozen,npm ci, …); - the services, with the users and databases CI sets up;
- the activation of the hook manager when the repository uses one:
pre-commit installorlefthook install(husky activates itself through itspreparescript); - the service variables, as
export NAME=VALUElines appended to$CLAUDE_ENV_FILE.
Keep it idempotent and well within the hook timeout.
7. CI gate
Add the gate for pull/merge request pipelines only. Start from the snippet init --ci printed, or from docs/ci/. Pull requests from forks never skip and the default branch never skips; say so in the pull request.
- GitHub Actions: a first job that checks out the pull request's head commit with enough history and uses
CapeOfGoodCode/prepush-ci@<ref>(pin a release tag or a commit sha), which exposesverified; every other pull request job getsneeds: <gate>plusif: needs.<gate>.outputs.verified != 'true'. Jobs onpushto the default branch keep running unconditionally. Mention that the gate costs one rounded minute per workflow. - GitLab CI: a
rules:entry that skips merge request pipelines when$CI_COMMIT_MESSAGEcontains the trailer, plusprepush-ci verify "$CI_COMMIT_SHA"in the first job for the committer check. - Other systems: call
prepush-ci verify "$SHA"first and exit early with success when it returns 0.
Show the diff and say plainly: this change is where CI minutes are saved, and the default branch stays the backstop.
8. Documentation
Add a short section to CLAUDE.md (or AGENTS.md, whichever the repository uses):
- In cloud sessions
git pushruns the full check and takes about as long as CI; run it with a long timeout (the Bash tool's maximum), not the default. - What
Prepush-CI: fullmeans: the commit can only be pushed after the full check passed on it. - Never use
--no-verify. To push session commits from a machine that cannot run the full check, runprepush-ci strip <base>; CI then runs normally. - Push one branch at a time (pre-commit hooks see only the first ref).
- After a push of a commit with the trailer to a branch that has a pull request, show the result on it: run
prepush-ci report --markdown --result passed --tree "$(git rev-parse 'HEAD^{tree}')", with--junit "$(git rev-parse --show-toplevel)/.prepush-ci/junit.xml"and--coverage "$(git rev-parse --show-toplevel)/.prepush-ci/coverage.json"added for each of those files the check writes (none for a file the setup left out; the paths start at the top of the worktree because you may run the call from a subdirectory, where.prepush-ci/junit.xmlalone does not exist), and put its output into the one comment of that check. Leave out the result files when the push said the check passed earlier, because the files on disk may belong to another tree. The post-push hook, where the repository has it, writes the short comment right after the push and your call then updates that comment: after a later push the comment shows the short text until you update it again. Find the comment whose body holds the marker line<!-- prepush-ci:followed by the check's name (the first line of the output) and update it; create a comment only when none holds the marker. Never use--edit-last: it edits the last comment of the user, whatever it says. If the branch has no pull request, post nothing.
Also add a sentence to the README for humans: how to opt in locally (export PREPUSH_CI=full) and that nothing changes for them otherwise.
9. Show the result after every push
The rule above depends on the agent remembering it. A Claude Code hook can do it after every successful git push: prepush-ci hook post-push runs after each command of the agent and, when the command pushed a commit with the trailer that passed the check, creates or updates the one comment of the check on the pull request of the branch; it does nothing when the branch has none. Tell the user in a sentence what the hook does and ask the user for a yes. Without a yes, change no file; the rule above stays for agents without hooks, and stays when the hook is added.
With the yes, add this group to hooks.PostToolUse of .claude/settings.json; keep every other setting, and add nothing when a command there already runs hook post-push:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "d=$(uv tool dir --bin 2>/dev/null) && [ -n \"$d\" ] && PATH=\"$d:$PATH\"; command -v prepush-ci >/dev/null 2>&1 && prepush-ci hook post-push || true",
"timeout": 30
}
]
}
]
}
}The command is d=$(uv tool dir --bin 2>/dev/null) && [ -n "$d" ] && PATH="$d:$PATH"; command -v prepush-ci >/dev/null 2>&1 && prepush-ci hook post-push || true: it puts the directory uv tool install uses in front of PATH only when uv prints one (an empty entry in PATH is the current directory, where a cloned repository could plant a prepush-ci), runs the hook only when prepush-ci is found, and exits 0 whatever happens. The settings file is committed, so every teammate gets the hook, and the hook does nothing until the tool is installed (uv tool install prepush-ci): tell the user so. The hook gives up by itself after 15 seconds and always exits 0; the timeout is the backstop.
10. Prove it
The SessionStart hook did not run for the current session. Then:
- Run
.claude/hooks/session-start.shby hand (withCLAUDE_CODE_REMOTE=trueandCLAUDE_ENV_FILEset) and source the exported variables into your shell. - Run
prepush-ci doctor --mode full; fix everything it reports. - Commit the setup on the branch. This commit may lack the trailer (the hooks were not installed yet when it was written); that is harmless, CI runs in full on it.
- Make a second, trivial commit (e.g. the docs section). Confirm with
git log -1 --format=%Bthat it carriesPrepush-CI: full. - Push with a long timeout; show that the full check ran and passed.
- Open the pull request (as a draft if the repository runs no CI on drafts, then mark it ready) and report what the CI did: the gate verified the head commit and skipped the other jobs.
Report to the user
End with: the confirmed check command, the services started in the session and their versions, what the gate skips and what it never skips, measured times (full check in the session vs. the last CI run), and anything left open (steps that cannot run in the container, CI drift if CI does not call the same entry point).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

