Update to Postman

{
  "name": "ci-integration",
  "description": "Common CI integrations that can added as independent pass/fail gates. Use when the user asks to \"add Postman to CI,\" \"run this collection on every PR,\" \"fail the build on a governance violation,\" or \"push to the postman cloud workspace after merge to main\", \"add some api related operation in my Github actions\".",
  "included_files": [],
  "skill_md_contents": "---\nname: ci-integration\ndescription: Common CI integrations that can added as independent pass/fail gates. Use when the user asks to \"add Postman to CI,\" \"run this collection on every PR,\" \"fail the build on a governance violation,\" or \"push to the postman cloud workspace after merge to main\", \"add some api related operation in my Github actions\". \n---\n\n# CI Integration\n\n## Overview\nThese are some common workflows that one can add in their CI pipeline leveraging postman cli.\n\n## Run a collection — a gated pipeline step\n\n`postman collection run <path/id>` exits nonzero on a failed `pm.test`\nassertion, which is what makes it a usable gate — see `api-testing` for how\nthat exit code actually gets set. What's CI-specific: `-r junit,html` (or\n`--reporter-*-export`) writes a report your CI provider can surface as\nbuild artifacts or test annotations, instead of leaving the result buried in\na log. `--bail` stops the run early on the first failure when a fast signal\nmatters more than a full report.\n\n## Lint — pick the target that matches the gate you want\n\nThree verbs look interchangeable and aren't — only two of them apply your\norganization's governance rules, and the CLI's own `-h` output is where that\nbecomes visible (no assumption below goes further than what it printed):\n\n| Want to check | Command | Applies org governance? |\n| --- | --- | --- |\n| One spec against your rules | `spec lint <spec> --workspace-id <id> -f error` | Yes, via `--workspace-id` |\n| One collection's structure/style | `collection lint <path> -f error` | **No** — this verb takes no `--workspace-id` at all |\n| The whole workspace: every entity plus `.postman/resources.yaml` | `workspace lint --workspace-id <id> -f error` | Yes |\n\n`collection lint` is a schema/style check only — running it and reporting\n\"governance passed\" overstates what it did. If the ask is \"does this\ncollection violate our rules,\" `workspace lint` is the one that actually\nanswers it (and covers every collection in the repo in one pass); reach for\nbare `collection lint` only when there's no workspace to fetch rules from\nyet.\n\n## Push to workspace — only after merge\n\n`postman workspace push -y` is the one command in this skill that changes\nshared cloud state, so it belongs behind a merge-to-main trigger, not a PR\ntrigger. `-y` skips confirmation prompts a non-interactive job can't answer.\nLeave `--no-prepare` off — the default prepare step is what assigns real IDs\nto entities that are new since the last push; skipping it because a run\nfelt slow trades a few seconds for a push that silently fails to create\nanything new.\n\n`--push-strategy force-sync` mirrors the whole workspace, deleting any cloud\nentity with no local counterpart — genuinely destructive, and not the\ndefault for a reason. See Critical Rules before adding it to a merge job.\n\n## AI readiness threshold\n\n`collection ai-readiness <path> --min-score <n>` and its spec-side\ncounterpart `spec ai-readiness <path> --min-score <n>` (see `ai-readiness`\nskill) are a fourth, separate gate — they score AI-agent consumability, not\ntest results or governance/structural style. Keep either in its own step:\nfolding it into the same step as `run` or one of the `lint` verbs above\nhides which kind of check actually failed when the job goes red. Pick the\nverb that matches what's checked into the repo — `collection ai-readiness`\nfor a git-synced collection, `spec ai-readiness` for an OpenAPI spec with no\ncollection generated from it yet.\n\n```yaml\n- run: postman collection ai-readiness ./postman/collections/My\\ API --min-score 70\n```\n\n## Critical Rules\n\n1. **Never collapse `run`, `lint`, and `ai-readiness` into one step, and\n   never pass `-x`/`--suppress-exit-code` to a CI run.** One combined exit\n   code hides which check broke; a suppressed one hides that anything broke\n   at all.\n2. **Gate `workspace push` to the merge event, never a PR event.** Everything\n   else in this skill is read-only against the cloud; this is the one\n   command that writes to it, so a PR-triggered push ships an unmerged\n   branch's entities to the shared workspace.\n3. **`--push-strategy force-sync` deletes cloud entities absent locally.**\n   Only add it to a job whose explicit job is mirroring the workspace exactly,\n   with that intent confirmed — never as the default merge step, where the\n   default (create/update-only) strategy is the safe choice.\n4. **Authenticate once, non-interactively:**\n   `postman login --with-api-key \"$POSTMAN_API_KEY\"`, reading the key from\n   the CI provider's secret store. Don't reach for `collection run`'s\n   `--postman-api-key` as the general answer — it's US-region only — and\n   `spec lint`/`workspace push` don't take it at all.\n\n   ```yaml\n   # WRONG — key committed in plain text, and scoped to one command anyway\n   - run: postman collection run api.json --postman-api-key PMAK-abc123...\n\n   # CORRECT — one non-interactive login, key from the provider's secret store\n   - run: postman login --with-api-key \"$POSTMAN_API_KEY\"\n   - run: postman collection run api.json\n   - run: postman spec lint spec.yaml --workspace-id $WS -f error\n   ```\n5. **Never `newman run` in place of `postman collection run`.** The CLI is\n   the supported runner every other skill here assumes; Newman forks the\n   toolchain and skips whatever reporting/governance depends on the CLI\n   specifically.\n\n## Verification\n\nState each gate that ran and its individual result — not \"CI passed,\" but\nwhich check ran, what it checked (governance vs. structure per the Lint\ntable above, or AI-agent consumability for `ai-readiness`), and its exit\ncode. If `workspace push` ran, confirm it was triggered by the merge event\nand not a PR event, state which push strategy was used, and report\n`Created`/`Updated` per entity rather than just \"push succeeded.\" Confirm\nno secret value appears literally in the committed workflow file.\n\n## Reference\n\n- `api-testing` skill — `collection run`'s exit-code semantics and reporter\n  flags in full.\n- `collection-schema-v3` skill — what `workspace push` is actually pushing.\n- `bootstrap` skill — CLI resolution, workspace linking, `.postman/resources.yaml`.\n- `ai-readiness` skill — `collection ai-readiness`, `spec ai-readiness`, and\n  their `--min-score` gate.\n"
}