{"id":49370709,"url":"https://github.com/threemoonslab/agents-shipgate","last_synced_at":"2026-05-02T03:01:41.269Z","repository":{"id":353707012,"uuid":"1220594946","full_name":"ThreeMoonsLab/agents-shipgate","owner":"ThreeMoonsLab","description":"agents-shipgate · static release-readiness scanner for AI agent tool surfaces. Reads MCP, OpenAPI, OpenAI Agents SDK, Anthropic Messages API, Google ADK. Produces Markdown, JSON, SARIF. CLI + GitHub Action. Apache-2.0.","archived":false,"fork":false,"pushed_at":"2026-04-29T04:45:45.000Z","size":466,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T01:35:17.749Z","etag":null,"topics":["agent-governance","agent-tooling","agents","ai-agents","anthropic","ci-cd","github-actions","google-adk","llm","mcp","openai-agents-sdk","openapi","python","release-engineering","release-readiness","sarif","static-analysis","tool-use"],"latest_commit_sha":null,"homepage":"https://threemoonslab.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThreeMoonsLab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-25T04:42:24.000Z","updated_at":"2026-04-29T04:41:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"da027393-c4c2-4de8-bac9-96c8f48880d0","html_url":"https://github.com/ThreeMoonsLab/agents-shipgate","commit_stats":null,"previous_names":["threemoonslab/agents-shipgate"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ThreeMoonsLab/agents-shipgate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThreeMoonsLab%2Fagents-shipgate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThreeMoonsLab%2Fagents-shipgate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThreeMoonsLab%2Fagents-shipgate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThreeMoonsLab%2Fagents-shipgate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThreeMoonsLab","download_url":"https://codeload.github.com/ThreeMoonsLab/agents-shipgate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThreeMoonsLab%2Fagents-shipgate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32482460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-governance","agent-tooling","agents","ai-agents","anthropic","ci-cd","github-actions","google-adk","llm","mcp","openai-agents-sdk","openapi","python","release-engineering","release-readiness","sarif","static-analysis","tool-use"],"created_at":"2026-04-27T23:00:48.590Z","updated_at":"2026-05-01T02:00:38.158Z","avatar_url":"https://github.com/ThreeMoonsLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/readme-header-dark.png\"\u003e\n    \u003cimg src=\"assets/readme-header.png\" alt=\"Agents Shipgate · static release-readiness for AI agent tool surfaces\" width=\"100%\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n# Agents Shipgate\n\n[![PyPI](https://img.shields.io/pypi/v/agents-shipgate)](https://pypi.org/project/agents-shipgate/)\n[![Python](https://img.shields.io/pypi/pyversions/agents-shipgate)](https://pypi.org/project/agents-shipgate/)\n[![GitHub Action](https://img.shields.io/badge/GitHub%20Action-marketplace-blue)](https://github.com/marketplace/actions/agents-shipgate)\n[![License](https://img.shields.io/pypi/l/agents-shipgate)](LICENSE)\n[![CI](https://github.com/ThreeMoonsLab/agents-shipgate/actions/workflows/ci.yml/badge.svg)](https://github.com/ThreeMoonsLab/agents-shipgate/actions/workflows/ci.yml)\n\nStatic release-readiness scanner for AI agent tool surfaces.\n\n**agents-shipgate is an open-source CLI and GitHub Action that produces release-readiness reports for AI agent tool surfaces.** It reads a manifest plus tool sources and writes deterministic findings as Markdown, JSON, and SARIF.\n\n**Inputs:** OpenAI Agents SDK · Anthropic Messages API · Google ADK · MCP · OpenAPI · OpenAI Agents API.\n**Outputs:** Markdown · JSON · SARIF.\n\n## Install\n\n```bash\npipx install agents-shipgate\n# or in CI:\n# - uses: ThreeMoonsLab/agents-shipgate@v0.4.0\n```\n\n## 60-second run\n\n```bash\nagents-shipgate init --workspace . --write\nagents-shipgate scan -c shipgate.yaml\n# writes agents-shipgate-reports/report.md and report.json\n```\n\nTo verify your install on a known fixture without writing any YAML:\n\n```bash\nagents-shipgate fixture run support_refund_agent\n```\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| `0` | Pass (advisory mode or strict-no-blockers) |\n| `2` | Manifest config error |\n| `3` | Input parse error (file missing, malformed, path traversal blocked) |\n| `4` | Other Agents Shipgate error |\n| `20` | Strict-mode gate failure |\n\n## For coding agents\n\nAgents Shipgate is designed to be agent-friendly. If you're a coding agent (Claude Code, Codex, Cursor, Aider) reading this repo:\n\n- **[`AGENTS.md`](AGENTS.md)** — canonical agent-facing instructions: install, run, common tasks, JSON-mode flags, error semantics\n- **[`STABILITY.md`](STABILITY.md)** — what won't break across `0.x` versions\n- **[`prompts/`](prompts/)** — reusable prompts for common workflows\n- **[`docs/manifest-v0.1.json`](docs/manifest-v0.1.json)** + **[`docs/report-schema.v0.4.json`](docs/report-schema.v0.4.json)** — JSON Schemas for live editor validation\n- **[`docs/checks.json`](docs/checks.json)** — machine-readable check catalog\n\nEvery command has a `--json` form. Errors emit a structured `next_action` line on stderr when `AGENTS_SHIPGATE_AGENT_MODE=1`.\n\n## Why this exists\n\nOnce an AI agent can refund, email, cancel, deploy, or modify a record, every tool change becomes a release event. Code review catches code; eval suites catch behavior; observability catches runtime. None of them answer the release question: *given the tool surface declared in this PR, do we have explicit approval policies, scope coverage, idempotency evidence, and review readiness for every action?*\n\nShipgate produces a deterministic answer to that question, before promotion.\n\n## Findings Gallery\n\nThe bundled support-refund fixture demonstrates the kind of release risks Agents Shipgate is designed to surface:\n\n```text\n## Agents Shipgate\n\nStatus: Release blockers detected\nCritical: 2 - High: 14 - Medium: 2\nHuman review: recommended\n\nTop findings:\n1. stripe.create_refund lacks a declared approval policy\n2. stripe.create_refund lacks idempotency evidence\n3. Manifest declares broad permission scopes\n```\n\n- `stripe.create_refund` lacks a declared approval policy, so a financial action could ship without an explicit human review gate.\n- `stripe.create_refund.amount` lacks a maximum bound, weakening blast-radius control.\n- `stripe.create_refund` lacks idempotency evidence while retry behavior is known, risking duplicate refunds.\n- `wildcard_mcp_tools.*` exposes a wildcard tool surface, making review incomplete.\n- `gmail.send_customer_email` overlaps a prohibited external-communication action without a matching confirmation policy.\n\n## Why Not Just...\n\n| Alternative | Gap Agents Shipgate Covers |\n| --- | --- |\n| Unit tests | Tests usually validate code paths, not the released tool surface and declared policies. |\n| Code review | Reviewers miss generated specs, MCP exports, broad scopes, and missing approval policies. |\n| Runtime traces | Useful later, but they arrive after behavior exists. Agents Shipgate runs before promotion. |\n| Nothing | Tool-surface drift becomes a production surprise. |\n\n## Quickstart\n\nUse Agents Shipgate as a [GitHub Action](#github-action) on every PR, or run the CLI locally.\n\nInstall the published package:\n\n```bash\npython -m pip install agents-shipgate\nagents-shipgate --version\n```\n\nInstall from a source checkout when developing locally:\n\n```bash\npython -m pip install -e \".[dev]\"\nagents-shipgate init --workspace . --write\nagents-shipgate doctor --config shipgate.yaml\nagents-shipgate scan --config shipgate.yaml\n```\n\nOr install directly from GitHub when testing the latest unreleased source:\n\n```bash\npython -m pip install \"git+https://github.com/ThreeMoonsLab/agents-shipgate@main\"\n```\n\nTry the bundled fixture:\n\n```bash\nagents-shipgate scan --config samples/support_refund_agent/shipgate.yaml\nagents-shipgate scan --config samples/simple_openai_api_agent/shipgate.yaml\nagents-shipgate scan --config samples/google_adk_agent/shipgate.yaml\nagents-shipgate scan --config samples/clean_read_only_agent/shipgate.yaml\n```\n\n## CI Behavior\n\nCI is advisory by default:\n\n```bash\nagents-shipgate scan --config shipgate.yaml --ci-mode advisory\n```\n\nStrict mode exits with code `20` only when unsuppressed critical findings exist.\nConfiguration, input parsing, and internal tool errors use `2`, `3`, and `4` respectively:\n\n```bash\nagents-shipgate scan --config shipgate.yaml --ci-mode strict\n```\n\nFor existing projects, save the current reviewed findings as a local baseline and\nfail strict CI only on new unsuppressed findings:\n\n```bash\nagents-shipgate baseline save --config shipgate.yaml --out .agents-shipgate/baseline.json\nagents-shipgate scan --config shipgate.yaml --baseline .agents-shipgate/baseline.json --ci-mode strict\n```\n\nTeams can override severities and CI failure thresholds:\n\n```yaml\nchecks:\n  severity_overrides:\n    SHIP-AUTH-MISSING-SCOPE: critical\nci:\n  fail_on:\n    - critical\n    - high\n```\n\n## Google ADK\n\nAgents Shipgate supports static Google ADK extraction for Python entrypoints and Agent Config YAML. The adapter detects `LlmAgent`/`Agent` definitions, function tools, `OpenAPIToolset`, `McpToolset`, callbacks, plugins, sub-agents, eval references, and explicit local tool inventories without importing ADK code.\n\n```yaml\nversion: \"0.1\"\nproject:\n  name: adk-support-agent\nagent:\n  name: support-agent\n  declared_purpose:\n    - handle support cases\nenvironment:\n  target: production_like\ntool_sources:\n  - id: adk\n    type: google_adk\n    path: agent.py\ngoogle_adk:\n  eval_sets:\n    - evals/support.eval.json\n  tool_inventories:\n    - inventories/adk-mcp-tools.json\n```\n\nDynamic ADK toolsets produce warnings or findings unless you provide explicit MCP, OpenAPI, or local tool inventory inputs.\n\n## Policy Packs\n\nv0.4 adds local declarative YAML policy packs for organization-specific release\nrules. Policy packs are static data and run without importing code.\n\n```yaml\nchecks:\n  policy_packs:\n    - path: policies/org-release.yaml\n```\n\n```bash\nagents-shipgate scan --config shipgate.yaml --policy-pack policies/org-release.yaml\n```\n\n## Who It Is For\n\n| Buyer | Pain | Pitch | Next step |\n| --- | --- | --- | --- |\n| Platform engineer shipping a first production agent | \"I don't know what I don't know.\" | Audits manifest and tool schemas for release risks code review misses. | Run `agents-shipgate init --workspace . --write`. |\n| Security or GRC reviewer | \"Agents bypass existing controls.\" | Creates a static tool-surface audit trail for review. | Review the [check catalog](docs/checks.md). |\n| AI PM with a shipping deadline | \"Security review blocks us late.\" | Gives teams self-serve pre-review before formal approval. | Scan the [support-refund fixture](samples/support_refund_agent/shipgate.yaml). |\n\n## Limitations\n\nAgents Shipgate is a static, manifest-first scanner. It is intentionally narrow:\n\n- It does not run agents, call tools, invoke LLMs, or verify model availability.\n- It does not verify runtime behavior, latency, prompt quality, or routing decisions.\n- It does not replace dynamic security testing or human security review of the underlying systems.\n- It only inspects what is declared in `shipgate.yaml`, local OpenAPI specs, MCP exports, simple OpenAI API artifacts, optional SDK AST metadata, and static Google ADK inputs; tools that are not declared or statically discoverable are not scanned.\n- The manifest remains `version: \"0.1\"` in v0.4 so existing configs keep working. Reports add `report_schema_version: \"0.4\"` while preserving the v0.1 payload keys.\n\nSee [ROADMAP.md](ROADMAP.md) for what is planned next.\n\n## Trust Model\n\n**Agents Shipgate does not import user code, run agents, call tools, call LLMs, connect to MCP servers, make network calls, or collect telemetry by default.**\n\nSee [Trust model](docs/trust-model.md) and [Security policy](SECURITY.md) for the default local-only guarantees and disclosure process.\n\n## GitHub Action\n\nUse a pinned release tag for CI. Set `permissions: contents: read` and run on `pull_request`:\n\n```yaml\nname: Agents Shipgate\n\non:\n  pull_request:\n\npermissions:\n  contents: read\n\njobs:\n  agents-shipgate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd\n      - id: agents-shipgate\n        uses: ThreeMoonsLab/agents-shipgate@v0.4.0\n        with:\n          config: shipgate.yaml\n          ci_mode: advisory\n          output_dir: agents-shipgate-reports\n```\n\nFor PR comments, add `pull-requests: write` to the job's `permissions` and set `pr_comment: \"true\"`.\n\nInputs: `config`, `ci_mode` (`advisory` or `strict`), `fail_on`, `baseline`, `baseline_mode`, `policy_packs`, `no_plugins`, `output_dir`, `upload_artifact`, `pr_comment`, `github_token`, `shipgate_version`.\n\nOutputs: `status`, `critical_count`, `high_count`, `medium_count`, `baseline_new_count`, `baseline_matched_count`, `baseline_resolved_count`, `adk_agent_count`, `adk_dynamic_toolset_count`, `report_json`, `report_markdown`, `report_sarif`, `exit_code`.\n\nSet `shipgate_version` to install a pinned PyPI release instead of the action source when your workflow requires package/version parity.\n\n## Pricing And Open Source Stance\n\nAgents Shipgate is and will remain free OSS for individuals and teams running it on their own infrastructure. The core manifest-first scanner, built-in checks, Markdown report, and JSON report are intended to remain open source. We do not collect telemetry and do not require an account.\n\nIf hosted dashboards, SSO, org-wide baselines, approval workflows, or trace-based evidence emerge, they should live in a separate optional product rather than moving core OSS functionality behind a paywall.\n\n## Docs\n\n- [Agent Release Gate category](docs/category.md)\n- [Manifest v0.1](docs/manifest-v0.1.md)\n- [Check catalog](docs/checks.md)\n- [Policy packs](docs/policy-packs.md)\n- [Baseline workflow](docs/baseline.md)\n- [JSON report schema v0.4](docs/report-schema.v0.4.json)\n- [Trust model](docs/trust-model.md)\n- [Runtime inventory design note](docs/runtime-inventory.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Integration recipes](docs/integrations.md)\n- [Distribution plan](docs/distribution.md)\n- [JSON report schema v0.2](docs/report-schema.v0.2.json)\n- [JSON report schema v0.1](docs/report-schema.v0.1.json)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreemoonslab%2Fagents-shipgate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreemoonslab%2Fagents-shipgate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreemoonslab%2Fagents-shipgate/lists"}