Terminal
Terminal/Skill
Adds Postman collection runs, linting, AI readiness checks, and workspace pushes to CI as separate pass or fail gates.
By Postman
Works with
npx skills add postmanlabs/skills --skill ci-integrationThese are some common workflows that one can add in their CI pipeline leveraging postman cli.
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.
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):
| Want to check | Command | Applies org governance? |
|---|---|---|
| One spec against your rules | spec lint <spec> --workspace-id <id> -f error | Yes, via --workspace-id |
| One collection's structure/style | collection lint <path> -f error | No — this verb takes no --workspace-id at all |
The whole workspace: every entity plus .postman/resources.yaml | workspace lint --workspace-id <id> -f error | Yes |
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.
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.
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
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.
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.
--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.
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.
# 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
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.
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.
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.