Quickstart by CI

Moatgator plugs into CI through one CLI (moatgator). The GitHub Action is a thin wrapper around the same code, so behavior and exit codes are identical.

CI	Credential	Guide
GitHub Actions	OIDC (no stored key)	GitHub Actions
GitLab CI	API key as a masked variable	GitLab CI
Bitbucket Pipelines	API key as a secured variable	Bitbucket Pipelines
CircleCI	API key in a context	CircleCI
Anything else	API key	Generic

Credentials

• OIDC (GitHub Actions only): the job exchanges its GitHub token for a Moatgator token that lasts 10 minutes. Nothing long-lived to leak. You create a trust rule in the console first; without one, nobody gets in. Details.
• API key (mg_live_…): create it in the console under the app's keys, with only builds:write and builds:read. Store it as a masked, protected CI variable. Never commit it, never echo it. Rotate it from the console.

Exit codes (all CIs)

Code	Meaning
0	ok
1	internal error
2	invalid usage (unknown option, missing file or version)
3	authentication (no credential, key refused, missing scope, OIDC refused)
4	failure (package refused, grade below the minimum, invalid moatgator.yml, API or network error, --require-protected without a protected package)
5	timeout (--timeout, default 600 s)

Preview engine, unpublished packages

moatgator protect registers the build and uploads the package, but no protected package is produced yet; the command says so. The CLI and the Action are not published to npm or the Marketplace yet, so the npx moatgator commands in these guides work once the package is released. See the state table on the introduction.

Good practice for every CI

• Run on release tags or protected branches, not on pull requests from forks. Fork pull requests must not receive credentials.
• Pin third-party actions or images to a full commit SHA or digest.
• Start with scan (no credential needed), then add protect.
• Use --json when you want to parse the result; human messages go to stderr.