All posts
· Three Moons Lab

How to add Agents Shipgate to GitHub Actions in 5 minutes

Drop a workflow into .github/workflows/, set advisory mode, and every PR gets a structured tool-surface review with severity counts and finding evidence.

tutorialgithub-actionsci-cdrelease-readiness

The smallest useful integration of Agents Shipgate into a real workflow takes about five minutes and one PR. Advisory mode means it never blocks a merge until you flip it to strict — which makes it safe to add to any active repo today.

This is the literal sequence.

1. Add the workflow

Create .github/workflows/shipgate.yml:

name: Agents Shipgate

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  agents-shipgate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ThreeMoonsLab/[email protected]
        with:
          config: shipgate.yaml
          ci_mode: advisory
          pr_comment: "true"

That’s it for the workflow side. Notes:

  • Pin the version — @v0.5.1 not @main. The action is small and deterministic, but you don’t want a new release silently changing your CI behavior.
  • pull-requests: write is required for the PR comment. Drop it if you don’t want comments and rely on the Actions tab instead.
  • Advisory mode never fails CI. It posts findings and exits 0. Strict mode comes later.

2. Add a manifest

If your repo doesn’t already have a shipgate.yaml, generate one:

pipx install agents-shipgate
agents-shipgate init --workspace . --write

This produces a shipgate.yaml with CHANGE_ME placeholders for the agent name and declared purpose. Open it, replace the placeholders, and point tool_sources at whatever produces your agent’s tool surface — an OpenAPI spec, an MCP export, an OpenAI Agents SDK Python entrypoint, an Anthropic tools JSON, or a Google ADK config.

A minimal example:

version: "0.1"
project:
  name: my-agent
agent:
  name: my-agent
  declared_purpose:
    - look up support cases
    - answer questions from the help center
environment:
  target: production_like
tool_sources:
  - id: mcp_server
    type: mcp
    path: mcp/tools.json

Commit both files to a feature branch and open a PR.

3. What you get

On every PR, the action runs the same scan as the local CLI and posts a structured comment:

## Agents Shipgate

Status: Release blockers detected
Critical: 1 · High: 4 · Medium: 2

Top findings:
1. issue_refund lacks a declared approval policy   [SHIP-POLICY-APPROVAL-MISSING]
2. issue_refund lacks idempotency evidence         [SHIP-SIDEFX-IDEMPOTENCY-MISSING]
3. wildcard_mcp_tools.* exposes wildcard surface   [SHIP-INVENTORY-WILDCARD]

Reports:
- agents-shipgate-reports/report.md
- agents-shipgate-reports/report.json
- agents-shipgate-reports/report.sarif

In the Actions tab you also get the full markdown report as an artifact, plus a SARIF upload that lights up GitHub’s native code-scanning UI on the Files Changed view.

In advisory mode, the workflow always exits 0 — your existing required checks decide whether the PR can merge. The Shipgate run is informational.

4. When to flip to strict

Once the team has reviewed a baseline scan and resolved (or explicitly suppressed) the existing critical findings:

agents-shipgate baseline save -c shipgate.yaml \
  --out .agents-shipgate/baseline.json

Commit the baseline file, then in the workflow:

      - uses: ThreeMoonsLab/[email protected]
        with:
          config: shipgate.yaml
          ci_mode: strict
          fail_on: critical,high
          baseline: .agents-shipgate/baseline.json

Strict mode with a baseline fails CI only on new unsuppressed findings. Existing tech-debt findings are recorded in the baseline as known and don’t break PRs that aren’t related to them. New findings introduced by a PR fail the build. This is the model that lets a team adopt strict gating without flipping every PR red overnight.

5. Common gotchas

  • No shipgate.yaml — the action exits with code 2 and a clear “config not found” message. Run init --write once, commit, fix.
  • Permissions — if you forgot pull-requests: write and asked for pr_comment: "true", the comment step silently no-ops. The action still runs and uploads artifacts.
  • First scan looks scary — the first scan against a real agent usually surfaces 5–15 findings, most of them legitimate. Use advisory mode while the team triages, then save a baseline and switch to strict.
  • No scanner telemetry, no scanner network calls — the action runs entirely on your runner with the manifest and the artifacts you point it at. It doesn’t connect to MCP servers, doesn’t call LLMs, doesn’t phone home.

What good looks like

A team that’s adopted Shipgate well usually has:

  • A shipgate.yaml checked into the repo, kept current with the agent’s actual tool surface
  • A .agents-shipgate/baseline.json reflecting reviewed pre-existing findings
  • The workflow above in strict mode with fail_on: critical,high
  • Documented suppressions for the rare false positive, with reason: explaining why

The PR comment becomes part of the standard review surface — alongside type-check, test, and lint results. A reviewer reads it, asks for remediation on new findings, and merges when it’s green.

Try it on your repo and tell us what’s missing.

Install agents-shipgate GitHub