Ci Integration

CI Integration

Overview

These are some common workflows that one can add in their CI pipeline leveraging postman cli.

Run a collection — a gated pipeline step

postman collection run <path/id> exits nonzero on a failed pm.test assertion, which is what makes it a usable gate — see api-testing for how that exit code actually gets set. What's CI-specific: -r junit,html (or --reporter-*-export) writes a report your CI provider can surface as build artifacts or test annotations, instead of leaving the result buried in a log. --bail stops the run early on the first failure when a fast signal matters more than a full report.

Lint — pick the target that matches the gate you want

Three verbs look interchangeable and aren't — only two of them apply your organization's governance rules, and the CLI's own -h output is where that becomes visible (no assumption below goes further than what it printed):

collection lint is a schema/style check only — running it and reporting "governance passed" overstates what it did. If the ask is "does this collection violate our rules," workspace lint is the one that actually answers it (and covers every collection in the repo in one pass); reach for bare collection lint only when there's no workspace to fetch rules from yet.

Push to workspace — only after merge

postman workspace push -y is the one command in this skill that changes shared cloud state, so it belongs behind a merge-to-main trigger, not a PR trigger. -y skips confirmation prompts a non-interactive job can't answer. Leave --no-prepare off — the default prepare step is what assigns real IDs to entities that are new since the last push; skipping it because a run felt slow trades a few seconds for a push that silently fails to create anything new.

--push-strategy force-sync mirrors the whole workspace, deleting any cloud entity with no local counterpart — genuinely destructive, and not the default for a reason. See Critical Rules before adding it to a merge job.

AI readiness threshold

collection ai-readiness <path> --min-score <n> and its spec-side counterpart spec ai-readiness <path> --min-score <n> (see ai-readiness skill) are a fourth, separate gate — they score AI-agent consumability, not test results or governance/structural style. Keep either in its own step: folding it into the same step as run or one of the lint verbs above hides which kind of check actually failed when the job goes red. Pick the verb that matches what's checked into the repo — collection ai-readiness for a git-synced collection, spec ai-readiness for an OpenAPI spec with no collection generated from it yet.

- run: postman collection ai-readiness ./postman/collections/My\ API --min-score 70

Critical Rules

1. Never collapse run, lint, and ai-readiness into one step, and never pass -x/--suppress-exit-code to a CI run. One combined exit code hides which check broke; a suppressed one hides that anything broke at all.

2. Gate workspace push to the merge event, never a PR event. Everything else in this skill is read-only against the cloud; this is the one command that writes to it, so a PR-triggered push ships an unmerged branch's entities to the shared workspace.

3. --push-strategy force-sync deletes cloud entities absent locally. Only add it to a job whose explicit job is mirroring the workspace exactly, with that intent confirmed — never as the default merge step, where the default (create/update-only) strategy is the safe choice.

4. Authenticate once, non-interactively: postman login --with-api-key "$POSTMAN_API_KEY", reading the key from the CI provider's secret store. Don't reach for collection run's --postman-api-key as the general answer — it's US-region only — and spec lint/workspace push don't take it at all.

   yaml

   # WRONG — key committed in plain text, and scoped to one command anyway- run: postman collection run api.json --postman-api-key PMAK-abc123...
   # CORRECT — one non-interactive login, key from the provider's secret store- run: postman login --with-api-key "$POSTMAN_API_KEY"- run: postman collection run api.json- run: postman spec lint spec.yaml --workspace-id $WS -f error

5. Never newman run in place of postman collection run. The CLI is the supported runner every other skill here assumes; Newman forks the toolchain and skips whatever reporting/governance depends on the CLI specifically.

Verification

State each gate that ran and its individual result — not "CI passed," but which check ran, what it checked (governance vs. structure per the Lint table above, or AI-agent consumability for ai-readiness), and its exit code. If workspace push ran, confirm it was triggered by the merge event and not a PR event, state which push strategy was used, and report Created/Updated per entity rather than just "push succeeded." Confirm no secret value appears literally in the committed workflow file.

Reference

• api-testing skill — collection run's exit-code semantics and reporter flags in full.
• collection-schema-v3 skill — what workspace push is actually pushing.
• bootstrap skill — CLI resolution, workspace linking, .postman/resources.yaml.
• ai-readiness skill — collection ai-readiness, spec ai-readiness, and their --min-score gate.