# shipcheck

> Your agent runs its tests with shipcheck run. That run, which shipcheck starts in its own clone, gives the GitHub check its PR waits for.

Your agent runs its tests with `shipcheck run`, and that run gives the GitHub check its PR waits for. shipcheck starts the run itself: it runs your checks locally, natively in an OS sandbox or as your workflows in containers with act, keeps the result for each git tree, and posts one required check per job, such as `shipcheck/test`.

## Setup

1. Install the binary: `brew install gabrielkoerich/tap/shipcheck`, or `curl -fsSL https://shipcheck.run/install.sh | sh` ([install](https://shipcheck.run/docs/install.md)).
2. Run `shipcheck init` in a clone of the repository, on `main`.
3. Commit the `shipcheck.toml` it writes and merge it to `main`.
4. Install the [shipcheck App](https://github.com/apps/shipcheck-run) on the repository. `init` prints this link.

## Docs

- [Install](https://shipcheck.run/docs/install.md): What shipcheck needs on the machine, and how to install it.
- [Quickstart](https://shipcheck.run/docs/quickstart.md): Set up a repository once, then each clone once, then work as usual.
- [Require the check](https://shipcheck.run/docs/branch-protection.md): Make main accept a PR only after its shipcheck check passes.
- [Agents](https://shipcheck.run/docs/agents.md): How a coding agent learns to run shipcheck instead of the tests and git commit, with any agent.
- [shipcheck.toml](https://shipcheck.run/docs/config.md): Every setting of the one file the repository owner writes.
- [Speed](https://shipcheck.run/docs/benchmarks.md): How long shipcheck took against GitHub's hosted runners on the same commits, the slower runs included.
- [Speed up runs](https://shipcheck.run/docs/speed.md): Use host mode, shard pytest, let jobs download, keep caches, and pick a Docker engine.
- [Commands](https://shipcheck.run/docs/cli.md): The commands, their exit codes and their environment variables.
- [How it works](https://shipcheck.run/docs/how-it-works.md): What shipcheck runs, where, and when it trusts a stored result.
- [What a green check proves](https://shipcheck.run/docs/proof.md): What a passing shipcheck job check guarantees, and what it does not.
- [Security](https://shipcheck.run/docs/security.md): What a job can reach on your machine, what the App can do on GitHub, what the service stores, and how to report a vulnerability.
- [Limits](https://shipcheck.run/docs/limits.md): What shipcheck does not catch, and what act cannot run.

## Agents

- [SKILL.md](https://shipcheck.run/SKILL.md): how an agent runs shipcheck, reads its result and fixes a failed check

## Optional

- [All docs in one file](https://shipcheck.run/llms-full.txt)
- [Source](https://github.com/gabrielkoerich/shipcheck): the Rust CLI, MIT