Reference

JSON output

shipcheck --json prints a single JSON document to stdout and nothing else, so it can be piped straight into other tools.

bash

$ shipcheck --json

stdout (abridged to three checks)

{  "ready": false,  "version": "v0.1.0",  "summary": {    "passed": 6,    "warnings": 1,    "failed": 3,    "skipped": 0  },  "duration_ms": 352,  "checks": [    {      "id": "git.clean",      "name": "Working tree",      "description": "Checks that there are no uncommitted or untracked changes.",      "status": "fail",      "message": "1 uncommitted change",      "suggestion": "Commit or stash your changes so you ship exactly what is in Git.",      "duration_ms": 9    },    {      "id": "tests",      "name": "Tests",      "description": "Detects and runs the project's test command (go test, npm test, pytest, cargo test, …).",      "status": "fail",      "message": "Tests failed (go test ./...)",      "suggestion": "Run `go test ./...` to see the full output.",      "duration_ms": 298    },    {      "id": "ci",      "name": "CI",      "description": "Detects CI configuration for GitHub Actions, GitLab CI, CircleCI, Jenkins, Bitbucket or Azure Pipelines.",      "status": "warn",      "message": "No CI configuration",      "suggestion": "Add a CI workflow so every push is tested (shipcheck runs in CI too).",      "duration_ms": 0    }  ]}

Report fields

Report fields
Field	Type	Description
`ready`	boolean	true when no check failed. Warnings don't affect it.
`version`	string	The Shipcheck version that produced the report.
`summary`	object	Counts: passed, warnings, failed, skipped.
`duration_ms`	number	Total run time in milliseconds.
`checks`	array	One entry per enabled check, in run order.

Check fields

Check fields
Field	Type	Description
`id`	string	Stable check ID, e.g. git.clean. Safe to match on.
`name`	string	Human-readable check name.
`description`	string	What the check does.
`status`	string	One of pass, warn, fail, skip (after severity is applied).
`message`	string	The one-line result, as shown in the terminal.
`suggestion`	string?	How to fix it. Omitted when there is nothing to suggest.
`duration_ms`	number	How long the check took.
`details`	string[]?	Only with --verbose: commands run, changed files, output tails.

Errors

If Shipcheck itself can't run (for example an invalid config file), it still prints JSON, with a single error field, and exits with code 2:

json

{  "error": ".shipcheck.yml: line 3: invalid severity \"loud\" (use error or warn)"}

Guarantees

No progress output, colors or text is mixed into stdout.
Exit codes are the same as in text mode. See Exit codes.
Secret values never appear. Only variable names do.
Check IDs are stable. New fields may be added, but existing ones won't change meaning.

Examples with jq

bash

# Is it ready?$ shipcheck --json | jq '.ready'# Only the problems$ shipcheck --json | jq '.checks[] | select(.status == "fail" or .status == "warn") | {id, message}'# Fail a script unless ready$ shipcheck --json | jq -e '.ready' > /dev/null

Found a mistake? Edit this page on GitHub