Getting started

Quick start

Run one command in your project, read the report, fix what blocks you, then ship.

1. Run it

From the root of your project:

bash

$ shipcheck

shipcheck and shipcheck check are the same command. To check another directory, pass --dir (or -C):

bash

$ shipcheck --dir ./services/api

2. Read the report

Each line is one check. When something needs attention, a suggestion follows it.

~/my-app

$ shipcheck SHIPCHECK ✓ Git repository✗ 1 uncommitted change  → Commit or stash your changes so you ship exactly what is in Git.✓ On branch main✗ Tests failed (go test ./...)  → Run `go test ./...` to see the full output.✓ Production build passed✗ 1 environment variable missing  → Set API_KEY in your environment or in .env.✓ README found✓ License found (MIT)✓ Version 1.4.0⚠ No CI configuration  → Add a CI workflow so every push is tested (shipcheck runs in CI too). ──────────────────────────── 6 passed · 1 warning · 3 failed ✗ Not ready to ship

Symbol	Status	Meaning
✓	`pass`	Nothing to do.
⚠	`warn`	Worth fixing, but doesn't block shipping.
✗	`fail`	Blocks shipping. Shipcheck exits with code 1.
–	`skip`	Not applicable, for example no test command found.

3. Dig into a failure

--verbose adds timings, the commands that ran, changed files and the last 20 lines of output from failing tests or builds. Secret values are redacted.

~/demo (excerpt)

$ shipcheck --verbose SHIPCHECKproject  /home/you/democonfig   none (using defaults) ✓ Git repository                                    5ms✗ 1 uncommitted change                              11ms  → Commit or stash your changes so you ship exactly what is in Git.    ?? notes.txt✓ On branch main                                    10ms✗ Tests failed (go test ./...)                      284ms  → Run `go test ./...` to see the full output.    $ go test ./...  (exit 1, 284ms)    --- FAIL: TestAdd (0.00s)        demo_test.go:7: expected 5    FAIL    FAIL	example.com/demo	0.003s    FAIL✓ Production build passed                           13ms    $ go build ./...  (13ms)

4. Adjust it (optional)

The defaults work for most projects. To change them, generate a config file:

bash

$ shipcheck init✓ Created .shipcheck.yml  Edit it to fit your project, then run `shipcheck`.

init detects your branch, test and build commands, and .env.example, and writes a commented file. It never overwrites an existing config unless you pass --force. See Configuration for every option.

5. Ship

Use the exit code to gate a deploy:

bash

$ shipcheck && ./deploy.sh

Commands and flags

Command	Description
`shipcheck`	Run all checks (same as `shipcheck check`).
`shipcheck init`	Create a `.shipcheck.yml`. `--force` overwrites.
`shipcheck version`	Print the version. `--verbose` adds build details.
`shipcheck help`	Show help for any command.

Flag	Description
`--verbose`	Show commands, output excerpts and timings.
`--json`	Print a JSON report instead of text.
`-c, --config`	Use a specific config file instead of `.shipcheck.yml`.
`-C, --dir`	Check another directory.
`--no-color`	Disable color. `NO_COLOR` is honoured too.
`--version`	Print the version and exit.

Found a mistake? Edit this page on GitHub