Skip to content

Manifest Reference

Jump to bottom
Pengfei Hu edited this page Apr 26, 2026 · 1 revision

Manifest Reference

shipgate.yaml schema, version 0.1. The manifest is validated strictly — unknown fields fail with a typo suggestion, and required fields are enforced by Pydantic.

version: "0.1"
project:
  name: my-agent          # required
  owner: support-eng      # optional
  repo: org/agents        # optional
agent:
  name: refund-assistant  # required
  declared_purpose:       # required (or instructions_preview, or openai_api.prompt_files)
    - issue customer refunds within policy
  prohibited_actions:
    - send mass marketing email
  instructions_preview: |
    Help customers with refund questions...
  sdk:
    type: openai_agents
    language: python
    entrypoint: agent.py
environment:
  target: production_like  # local | staging | production_like | production
tool_sources:
  - id: refund_api
    type: openapi          # mcp | openapi | openai_agents_sdk
    path: openapi/refunds.yaml
    optional: false
openai_api:                # optional, for OpenAI Agents API artifacts
  prompt_files: [prompts/system.md]
  function_schemas:
    - path: tools/issue_refund.json
      name: issue_refund
  response_formats:
    - path: schemas/refund_response.schema.json
      downstream_critical_fields: [decision, refund_amount]
permissions:
  scopes: [refunds:write]
policies:
  require_approval_for_tools:
    - tool: issue_refund
      reason: financial action
  require_confirmation_for_tools: []
  require_idempotency_for_tools:
    - tool: issue_refund
risk_overrides:
  tools:
    legacy_search:
      remove_tags: [destructive]    # disagree with the heuristic
      tags: [read_only]
      reason: read-only despite "delete_session_token" parameter
checks:
  ignore:
    - check_id: SHIP-DOC-MISSING-DESCRIPTION
      tool: legacy_search
      reason: tool is internal-only and slated for removal
  severity_overrides:
    SHIP-INVENTORY-TOOL-SURFACE-TOO-LARGE: low
ci:
  mode: strict             # advisory | strict
  fail_on: [critical, high]
output:
  directory: agents-shipgate-reports
  formats: [markdown, json]

version

Literal["0.1"]. Required. Any other value fails with a clear error message at load time.

project

Field Type Required
name string yes
owner string no
repo string no

project.name appears in the agent_id (agent:{project}/{agent}) and in the run ID hash; it does not affect fingerprints.

agent

Field Type Required Notes
name string yes
declared_purpose list[str] conditional Required unless instructions_preview or openai_api.prompt_files is present
prohibited_actions list[str] no Free-text. Tokens are matched against tool names/descriptions to fire SHIP-SCOPE-PROHIBITED-TOOL-PRESENT
instructions_preview string no First chars surfaced in the report
sdk object no See below

agent.sdk

Field Type
type string (e.g. openai_agents)
language string (python)
entrypoint string — relative path to the SDK Python file
static_extract bool, default true
deep_import bool, default false (deferred; not implemented)

environment

Field Type Notes
target local | staging | production_like | production Production targets fire SHIP-INVENTORY-LOW-CONFIDENCE-PRODUCTION-SURFACE and SHIP-MANIFEST-HIGH-RISK-OWNER-MISSING
promotion_from / promotion_to string Free-form audit trail

tool_sources

Array. Each entry:

Field Type Required Notes
id string yes Stable identifier surfaced in reports
type mcp | openapi | openai_agents_sdk yes
path string yes for mcp/openapi (the SDK type accepts a fallback agent.sdk.entrypoint) Relative to the manifest directory; must not escape it (path traversal blocked at v0.2)
trust string no Free-form
optional bool no If true, parse failures emit warnings instead of failing the scan

openai_api

For OpenAI Agents API release artifacts. Optional; supplements tool_sources with prompts, function schemas, response formats, traces, and policy rules.

openai_api:
  prompt_files: ["prompts/system.md"]                    # markdown/text
  tools:
    - path: tools/all_tools.json
  function_schemas:
    - path: tools/issue_refund.json
      name: issue_refund                                  # explicit if file omits 'name'
  response_formats:
    - path: schemas/refund_response.schema.json
      downstream_critical_fields: [decision, refund_amount]
  model_config:
    path: openai-config.json
  test_cases:
    - path: tests/refund_cases.json
  trace_samples:
    - path: traces/replay.jsonl                           # JSONL or JSON
  policy_rules:
    - path: policies/refund_policy.yaml

policy_rules files are merged with dict-update semantics across files; if multiple files define the same key, the last one wins. The keys approval_required, confirmation_required, idempotency_required augment policies.require_*_for_tools.

permissions

permissions:
  scopes: [refunds:write, customers:read]
  credential_mode: oauth2_client_credentials   # free-form
  notes: "Issued by platform-eng for refund-assistant."

scopes feeds three checks:

  • SHIP-AUTH-MANIFEST-BROAD-SCOPE — scopes containing *, admin, or :* are flagged
  • SHIP-AUTH-SCOPE-COVERAGE-MISSING — tool scopes not covered here fire
  • SHIP-MANIFEST-UNUSED-SCOPE — scopes not used by any tool fire

policies

Each list entry is either a string (just the tool name) or {tool, reason}.

policies:
  require_approval_for_tools:
    - tool: issue_refund
      reason: financial action
    - delete_account                        # shorthand
  require_confirmation_for_tools:
    - send_customer_email
  require_idempotency_for_tools:
    - issue_refund

Policies satisfy SHIP-POLICY-APPROVAL-MISSING, SHIP-POLICY-CONFIRMATION-MISSING, SHIP-SIDEFX-IDEMPOTENCY-MISSING for the named tools. Stale entries (tool not loaded) fire SHIP-MANIFEST-STALE-POLICY.

risk_overrides

risk_overrides:
  tools:
    issue_refund:
      tags: [financial_action]              # add hints (treated as high-confidence manual)
      remove_tags: [read_only]              # remove heuristic hints by tag
      owner: payments-eng                   # required for production high-risk tools
      confidence: manual
      reason: regulated path; reviewed by legal

Manual hints win over heuristics. Use remove_tags to suppress automatic hints you disagree with — the most common case is reverting a substring-matched destructive tag on a benign read.

checks

checks.ignore

checks:
  ignore:
    - check_id: SHIP-DOC-MISSING-DESCRIPTION
      tool: legacy_search                    # optional; omit for global suppression
      reason: tool deprecated 2026-Q2        # required, non-empty

Suppressed findings carry suppressed: true and suppression_reason in JSON output. They do not count toward severity totals. An empty reason fails manifest validation. Stale suppressions fire SHIP-MANIFEST-STALE-SUPPRESSION.

checks.severity_overrides

checks:
  severity_overrides:
    SHIP-INVENTORY-TOOL-SURFACE-TOO-LARGE: low      # demote
    SHIP-DOC-MISSING-DESCRIPTION: high              # promote

The override applies to every finding that check produces. The original severity is preserved in evidence.default_severity for audit. Severity overrides do not change a finding's fingerprint.

Note. A top-level check_severity_overrides field is also accepted for backwards compatibility and wins on conflict with checks.severity_overrides. Prefer the nested form.

ci

Field Default Notes
mode advisory strict exits 20 on findings matching fail_on
fail_on null (= ["critical"] in strict mode, [] in advisory) Override per repo
pr_comment true Action consults its own input; manifest field is informational
annotations false Reserved for future SARIF emit
upload_artifact true Action consults its own input

output

output:
  directory: agents-shipgate-reports
  formats: [markdown, json]            # subset of {markdown, json}

CLI flags --out and --format override these per invocation.

Cross-references

Agents Shipgate · Apache-2.0 · maintained by Three Moons Lab · Report a false positive

🏠 Home

Getting started

Reference

Workflows

Extending

Project

Clone this wiki locally