Quickstart

Quickstart

Get a meaningful finding on your own tool surface in under two minutes. Requires Python 3.12+.

1. Install

pipx install agents-shipgate     # recommended (isolated)
# or
python -m pip install agents-shipgate

Verify:

agents-shipgate --version
# prints the installed version

2. Generate a starter manifest

Run from the root of your repo:

agents-shipgate init --workspace . --write

init walks the workspace, detects MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, and n8n artifacts (look for tools/*.json, *openapi*.yaml, .codex-plugin/, prompts/*.md, etc.), and writes a shipgate.yaml skeleton with CHANGE_ME markers for things it can't infer (declared purpose, ownership, policies).

If you have nothing to detect, copy this minimal manifest:

version: "0.1"
project:
  name: my-agent
agent:
  name: my-agent
  declared_purpose:
    - explain what this agent is allowed to do
environment:
  target: local
tool_sources:
  - id: tools
    type: mcp
    path: mcp_tools.json

3. Scan

agents-shipgate scan -c shipgate.yaml

You should see a summary, top findings, and agents-shipgate-reports/report.md + report.json written to disk.

Decision: review_required          # release_decision.decision — the release gate
Critical: 0  High: 3  Medium: 5
Top findings:
  - SHIP-AUTH-MISSING-SCOPE: write_record lacks declared auth scopes
  - SHIP-DOC-MISSING-DESCRIPTION: legacy_action has a missing or too-short description
  - ...
Reports:
  - agents-shipgate-reports/report.{md,json,sarif}
  - agents-shipgate-reports/packet.{md,json,html}

The core loop: verify before merge

scan is the one-shot review. For an ongoing change, run the deterministic verifier on the diff before you merge — it returns a merge verdict:

agents-shipgate verify --base origin/main --head HEAD \
  --config shipgate.yaml --ci-mode advisory --format json

Read agents-shipgate-reports/report.json → release_decision.decision (blocked | review_required | insufficient_evidence | passed) — that is the merge gate. Omit --base/--head for local, uncommitted work so your working-tree edits are scanned instead.

4. Try it on a real public API

Don't have your own tool surface yet? Borrow DigitalOcean's:

mkdir do-test && cd do-test
curl -sLo openapi.yaml \
  https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml
cat > shipgate.yaml <<'EOF'
version: "0.1"
project:
  name: digitalocean-test
agent:
  name: do-ops-agent
  declared_purpose:
    - manage cloud infrastructure
environment:
  target: production_like
tool_sources:
  - id: do
    type: openapi
    path: openapi.yaml
permissions:
  scopes: ["*"]
EOF
agents-shipgate scan -c shipgate.yaml

You'll see hundreds of findings — every destructive endpoint missing a policy entry. See Real-World Examples for the full walkthrough.

5. Wire it into CI

Drop this into .github/workflows/agents-shipgate.yml:

name: Agents Shipgate
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  shipgate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # so verify can diff against the PR base
      - uses: ThreeMoonsLab/agents-shipgate@v0.10.0
        with:
          ci_mode: advisory
          diff_base: target        # enrich with the PR base/head diff
          pr_comment: 'true'

See CI Recipes for GitLab CI, CircleCI, and strict-mode patterns.

Common next steps

• Suppress a known finding → see Manifest Reference § checks.ignore
• Track findings over time → see Baseline Workflow
• Understand what each check means → see Check Catalog
• Got an unexpected error → see Troubleshooting