@postman-cse/onboarding-bootstrap 2.6.0 → 2.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +58 -179
  2. package/dist/action.cjs +76293 -73937
  3. package/dist/cli.cjs +76298 -73944
  4. package/dist/index.cjs +76295 -73937
  5. package/package.json +5 -4
package/README.md CHANGED
@@ -4,25 +4,17 @@
4
4
 
5
5
  Provisions a [Postman workspace](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/overview/) from an OpenAPI spec, generating baseline, smoke, and contract collections in one step.
6
6
 
7
- Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman-api-onboarding-action).
7
+ Every generated collection ships with executable contract tests compiled from your spec: OpenAPI request, response, schema, and security checks grounded in the governing RFCs, plus dedicated gRPC, SOAP, GraphQL, AsyncAPI, and MCP lanes. The full test inventory and the standard behind each check: [Generated assertions](docs/generated-assertions.md) and [Multi-Protocol Contract Assertions](docs/MULTIPROTOCOL-ASSERTIONS.md).
8
8
 
9
- > **Standards-grounded assertion generation.** Every collection this action generates ships with executable contract tests compiled from your spec. For OpenAPI: operation mapping, status-code, `Content-Type`, response-header, request/response body, parameter, security-credential, and `Content-Length` checks, with JSON Schema (draft-07 / 2020-12) body validation, dialect-exclusive keyword rejection, and RFC-checked formats (RFC 3339 timestamps, RFC 4122 UUIDs, RFC 3986 URIs, and more). Layered on top: RFC 9110 status-code, framing, and field-syntax requirements, RFC 9457 `application/problem+json` error bodies with RFC 8259 encoding and RFC 8288 `Link` checks, RFC 6265 `Set-Cookie`, RFC 6797 HSTS and security headers, WHATWG Fetch CORS, RFC 9651 structured fields, RFC 9209 typed `Proxy-Status`, RFC 9421 message signatures, RFC 9530 body digests, `Accept` negotiation, media-type conventions (NDJSON, multipart boundaries, HAL, JSON:API), authentication-scheme credential grammar, preconditions and RFC 6902 / RFC 7386 patch bodies, `Deprecation`/`Sunset` advisories, and OpenAPI links/servers resolution. Beyond REST: canonical proto3 JSON well-known-type validation for gRPC with per-streamed-message shape checks and metadata/trailer wire-conformance, version-aware SOAP 1.1/1.2 media-type and Fault-status checks, GraphQL-over-HTTP media-type/status discipline, static AsyncAPI WebSocket / Socket.IO / MQTT message validation, and static MCP server-manifest contract checks. The full test inventory and the standard behind each check: [Generated assertions](docs/generated-assertions.md) and [Multi-Protocol Contract Assertions](docs/MULTIPROTOCOL-ASSERTIONS.md).
9
+ Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman-api-onboarding-action); the composite action's README has the full [action-picker table](https://github.com/postman-cs/postman-api-onboarding-action#which-action-should-i-use).
10
10
 
11
- ## Which action should I use?
12
-
13
- | Need | Use |
14
- | --- | --- |
15
- | Full API onboarding pipeline | [`postman-cs/postman-api-onboarding-action`](https://github.com/postman-cs/postman-api-onboarding-action) |
16
- | Mint a service-account access token for the pipeline | [`postman-cs/postman-resolve-service-token-action`](https://github.com/postman-cs/postman-resolve-service-token-action) |
17
- | Create or refresh Postman workspaces, specs, and generated collections | This bootstrap action |
18
- | Discover OpenAPI specs from AWS services | [`postman-cs/postman-aws-spec-discovery-action`](https://github.com/postman-cs/postman-aws-spec-discovery-action) |
19
- | Apply a curated flow.yaml to the Smoke collection | [`postman-cs/postman-smoke-flow-action`](https://github.com/postman-cs/postman-smoke-flow-action) |
20
- | Sync generated Postman artifacts back to the repo | [`postman-cs/postman-repo-sync-action`](https://github.com/postman-cs/postman-repo-sync-action) |
21
- | Link Insights discovered services to the workspace | [`postman-cs/postman-insights-onboarding-action`](https://github.com/postman-cs/postman-insights-onboarding-action) |
22
-
23
- ## Region
24
-
25
- The action defaults to the US production region (`postman-region: us`). [EU data residency](https://learning.postman.com/docs/administration/enterprise/about-eu-data-residency/) teams should set `postman-region: eu` on this action and on the service-token step that feeds it.
11
+ - [Usage](#usage)
12
+ - [Common scenarios](#common-scenarios)
13
+ - [Inputs](#inputs) / [Outputs](#outputs)
14
+ - [CLI usage (non-GitHub CI)](#cli-usage-non-github-ci)
15
+ - [How it works](#how-it-works)
16
+ - [Dynamic contract tests](#dynamic-contract-tests)
17
+ - [Enforcement layers and error codes](#enforcement-layers-and-error-codes)
26
18
 
27
19
  ## Usage
28
20
 
@@ -52,13 +44,18 @@ jobs:
52
44
  credential-preflight: enforce
53
45
  ```
54
46
 
55
- Provide either `spec-url` (public HTTPS) or `spec-path` (a file in the checked-out repo) for the [Spec Hub import](https://learning.postman.com/docs/design-apis/specifications/import-a-specification/) path. Mint the `postman-access-token` with the [service-token action](https://github.com/postman-cs/postman-resolve-service-token-action): it is the primary credential and carries every Postman asset operation (workspace, spec, collection generation and mutation, tagging, team scope) over the access-token gateway. A [Postman service account](https://learning.postman.com/docs/administration/service-accounts/) PMAK for `postman-api-key` is optional — it mints and re-mints that access token and logs the Postman CLI in for `spec lint`. See [Obtaining Credentials](docs/credentials.md) for the credential matrix and legacy fallback.
47
+ Provide either `spec-url` (public HTTPS) or `spec-path` (a file in the checked-out repo) for the [Spec Hub import](https://learning.postman.com/docs/design-apis/specifications/import-a-specification/) path.
48
+
49
+ Mint the `postman-access-token` with the [service-token action](https://github.com/postman-cs/postman-resolve-service-token-action): it is the primary credential and carries every Postman asset operation. A [service account](https://learning.postman.com/docs/administration/service-accounts/) PMAK for `postman-api-key` is optional; it mints and re-mints that access token and logs the Postman CLI in for `spec lint`. See [Obtaining Credentials](docs/credentials.md) for the credential matrix and legacy fallback.
50
+
51
+ > [!NOTE]
52
+ > The action defaults to the US production region (`postman-region: us`). [EU data residency](https://learning.postman.com/docs/administration/enterprise/about-eu-data-residency/) teams should set `postman-region: eu` on this action and on the service-token step that feeds it.
56
53
 
57
54
  ## Common scenarios
58
55
 
59
56
  ### Git-first spec from the repository
60
57
 
61
- For Git-first workflows, read the OpenAPI document directly from the checked-out workspace instead of hosting it over HTTPS:
58
+ Read the OpenAPI document directly from the checked-out workspace instead of hosting it over HTTPS:
62
59
 
63
60
  ```yaml
64
61
  - uses: actions/checkout@v5
@@ -224,6 +221,8 @@ See [Team Identity](docs/team-identity.md) for sub-team discovery and team-ID de
224
221
  | `breaking-change-summary-json` | JSON summary of the OpenAPI breaking-change check | n/a | n/a |
225
222
  <!-- outputs-table:end -->
226
223
 
224
+ Regenerate both tables from `action.yml` with `npm run docs:tables`.
225
+
227
226
  ## CLI usage (non-GitHub CI)
228
227
 
229
228
  The same bootstrap is available as a CLI for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems. GitHub Actions users should continue using the `action.yml` interface.
@@ -256,193 +255,73 @@ bootstrap:
256
255
  - bootstrap.env
257
256
  ```
258
257
 
259
- Example Bitbucket Pipelines step:
260
-
261
- ```yaml
262
- pipelines:
263
- default:
264
- - step:
265
- image: node:24
266
- script:
267
- - npm install -g @postman-cse/onboarding-bootstrap
268
- - postman-bootstrap --project-name core-payments --spec-url "https://raw.githubusercontent.com/postman-cs/postman-bootstrap-action/main/examples/core-payments-openapi.yaml" --postman-api-key "$POSTMAN_API_KEY" --postman-access-token "$POSTMAN_ACCESS_TOKEN" --result-json bootstrap-result.json --dotenv-path bootstrap.env
269
- artifacts:
270
- - bootstrap-result.json
271
- - bootstrap.env
272
- ```
273
-
274
- Example Azure DevOps job:
275
-
276
- ```yaml
277
- steps:
278
- - task: NodeTool@0
279
- inputs:
280
- versionSpec: '24.x'
281
- - script: |
282
- npm install -g @postman-cse/onboarding-bootstrap
283
- postman-bootstrap --project-name core-payments --spec-url "https://raw.githubusercontent.com/postman-cs/postman-bootstrap-action/main/examples/core-payments-openapi.yaml" --postman-api-key "$(POSTMAN_API_KEY)" --postman-access-token "$(POSTMAN_ACCESS_TOKEN)" --result-json bootstrap-result.json --dotenv-path bootstrap.env
284
- displayName: Bootstrap Postman assets
285
- - publish: bootstrap-result.json
286
- - publish: bootstrap.env
287
- ```
258
+ The same command works verbatim on any Node 24 runner: Bitbucket Pipelines with a `node:24` image, or Azure DevOps after a `NodeTool@0` step with `versionSpec: '24.x'`.
288
259
 
289
260
  ## How it works
290
261
 
291
262
  The action handles the bootstrap slice of the Postman onboarding workflow: create or reuse a Postman workspace, assign governance, invite the requester and workspace admins, upload or update the spec in [Spec Hub](https://learning.postman.com/docs/design-apis/specifications/overview/), lint it with the [Postman CLI](https://learning.postman.com/docs/postman-cli/postman-cli-governance/), generate or reuse baseline, smoke, and contract collections, inject generated tests, apply tags, and reuse committed `.postman/resources.yaml` state when present. Inputs and outputs use kebab-case.
292
263
 
293
- - **Phase independence:** bootstrap succeeds on its own even when later pipeline stages (repo sync, Insights) fail, and reruns reuse existing assets. See [Bootstrap Phase Independence](docs/bootstrap-phase-independence.md).
294
- - **Team identity:** the team ID is resolved from the access-token session identity; org-mode tenants pass `workspace-team-id` for the sub-team that should own the workspace. See [Team Identity](docs/team-identity.md).
264
+ - **Phase independence:** bootstrap succeeds on its own even when later pipeline stages fail, and reruns reuse existing assets. See [Bootstrap Phase Independence](docs/bootstrap-phase-independence.md).
265
+ - **Team identity:** the team ID is resolved from the access-token session identity; org-mode tenants pass `workspace-team-id`. See [Team Identity](docs/team-identity.md).
295
266
  - **Git providers:** workspace-to-repository linking supports GitHub and GitLab, cloud and self-hosted. See [Git Provider Support](docs/git-provider-support.md).
296
267
  - **Spec handling:** operation summaries are normalized before upload, `spec-url` fetches are SSRF-hardened HTTPS with pinned DNS, and breaking-change comparison runs before any Postman mutation when enabled. See [OpenAPI Spec Handling](docs/spec-handling.md).
297
268
  - **Lifecycle modes:** `collection-sync-mode` (`refresh`/`version`, legacy `reuse`), `spec-sync-mode` (`update`/`version`), release-label derivation, ref-native state, cloud spec-to-collection syncing, and smoke monitoring. See [Lifecycle Modes and Operational Reference](docs/lifecycle-and-operations.md).
298
- - **Credentials:** `postman-access-token` is the primary credential and carries every asset operation over the gateway; the optional `postman-api-key` powers access-token minting and the Postman CLI `spec lint` login. See [Obtaining Credentials](docs/credentials.md).
299
- - **Protocol write split:** GraphQL and SOAP build v2.1.0 collections created through the public collections API with `postman-api-key`. gRPC builds a v3/Extensible Collection (the only schema with the `grpc-request` item type) and is created through the gateway EC API, which is access-token only — so gRPC **hard-requires** `postman-access-token` and fails fast with `EC_REQUIRES_ACCESS_TOKEN` when it is absent (`resolve-service-token` mints one). See [Multi-Protocol Contract Assertions](docs/MULTIPROTOCOL-ASSERTIONS.md).
300
- - **Required protocol coverage:** WebSocket / Socket.IO via AsyncAPI, AsyncAPI non-JSON payload validation, AsyncAPI 3.x, and MQTT / LLM / MCP all need production-grade contract assertion generation. Current gaps and required end state are tracked in [Multi-Protocol Contract Assertions](docs/MULTIPROTOCOL-ASSERTIONS.md#required-production-grade-coverage).
269
+ - **Credentials:** `postman-access-token` is the primary credential for every asset operation; the optional `postman-api-key` powers access-token minting and the Postman CLI `spec lint` login. See [Obtaining Credentials](docs/credentials.md).
270
+ - **Protocol write split:** GraphQL and SOAP build v2.1.0 collections through the public collections API with `postman-api-key`. gRPC builds a v3/Extensible Collection through the gateway EC API, which is access-token only — so gRPC **hard-requires** `postman-access-token` and fails fast with `EC_REQUIRES_ACCESS_TOKEN` when it is absent. See [Multi-Protocol Contract Assertions](docs/MULTIPROTOCOL-ASSERTIONS.md).
301
271
 
302
272
  ## Dynamic contract tests
303
273
 
304
274
  Before any durable contract collection is overwritten, the action hardens the generated `[Contract]` collection against the resolved OpenAPI 3.0/3.1 document: it bundles and validates the spec, requires exactly one generated request per eligible operation, instruments each request with OpenAPI-derived runtime checks (status codes, headers, body presence, `Content-Type`, JSON schemas, security credential presence, request parameter and body values), and enforces script safety and size gates. Spec updates capture the previous content hash so failed runs can roll back, and refresh mode stages generated collections before touching durable ones.
305
275
 
306
- Full pipeline, validation scope, OpenAPI semantics, limits, and rollback behavior are documented in [Dynamic Contract Tests](docs/dynamic-contract-tests.md).
307
-
308
- The user-facing inventory of everything above — the exact test names per protocol, the RFC or specification each check enforces, and what to do when one fails — is in [Generated Assertions](docs/generated-assertions.md).
276
+ Full pipeline, validation scope, OpenAPI semantics, limits, and rollback behavior: [Dynamic Contract Tests](docs/dynamic-contract-tests.md). The user-facing inventory — exact test names per protocol, the RFC each check enforces, and what to do when one fails — is in [Generated Assertions](docs/generated-assertions.md).
309
277
 
310
- ## Errors
278
+ ## Enforcement layers and error codes
311
279
 
312
- Dynamic contract failures and warnings use `CONTRACT_` error codes. Remediation guidance for each code:
280
+ The action enforces the OpenAPI contract at three points with three failure modes. The full architecture — what runs at bootstrap time versus inside the CI collection run, and why the same RFC rule appears in more than one layer — is in [Contract Enforcement Layers](docs/contract-enforcement-layers.md).
313
281
 
314
- | Error code | Meaning | Remediation |
282
+ | Layer | When | Effect |
315
283
  | --- | --- | --- |
316
- | `CONTRACT_SPEC_FETCH_BLOCKED` | Spec URL, ref URL, DNS result, redirect, or socket destination was not allowed. | Use public HTTPS spec/ref URLs that do not resolve to private or local networks. |
317
- | `CONTRACT_SPEC_FETCH_FAILED` | Allowed HTTPS fetch failed or redirected too many times. | Check availability, status codes, and redirect chains. |
318
- | `CONTRACT_REF_LIMIT_EXCEEDED` | External ref count exceeded the configured limit. | Reduce external ref fan-out or bundle the spec upstream. |
319
- | `CONTRACT_REF_DEPTH_EXCEEDED` | Ref nesting exceeded the configured limit. | Flatten recursive/deep ref chains. |
320
- | `CONTRACT_REF_SIZE_EXCEEDED` | A fetched resource or total fetched bytes exceeded limits. | Reduce spec/ref size or pre-bundle the document. |
321
- | `CONTRACT_SPEC_PARSE_FAILED` | The fetched document was not valid JSON/YAML object content. | Fix the source document syntax. |
322
- | `CONTRACT_SPEC_READ_FAILED` | The `spec-path` file could not be read from the workspace. | Verify the file exists at the configured path and that the workflow checked out the branch that contains it. |
323
- | `CONTRACT_SPEC_VALIDATION_FAILED` | The bundled document failed OpenAPI validation. | Fix [OpenAPI validation](https://learning.postman.com/docs/design-apis/specifications/validate-a-specification/) errors. |
324
- | `CONTRACT_UNSUPPORTED_OPENAPI_VERSION` | The document was not OpenAPI 3.0 or 3.1. | Provide an OpenAPI 3.0/3.1 document. |
325
- | `CONTRACT_NO_ELIGIBLE_OPERATIONS` | No eligible `paths` operations with responses were found. | Add path operations with responses. |
326
- | `CONTRACT_OPERATION_NO_RESPONSES` | A `paths` operation had no response definitions. | Add at least one OpenAPI response to each path operation. |
327
- | `CONTRACT_UNRESOLVED_REF` | A ref remained unresolved after secure bundling. | Fix the ref target or make the external ref HTTPS-accessible. |
328
- | `CONTRACT_UNSUPPORTED_SCHEMA_DIALECT` | A schema declared an unsupported JSON Schema dialect. | Use draft-07 or 2020-12-compatible schemas. |
329
- | `CONTRACT_SCHEMA_COMPILE_FAILED` | schemasafe could not compile a response/header schema. | Simplify or correct the unsupported schema. |
330
- | `CONTRACT_STATIC_REQUEST_CHECK_FAILED` | Generated request missed a required non-security parameter or body. | Adjust generation options or the spec so generated requests include required shape. |
331
- | `CONTRACT_STATIC_REQUEST_CHECK_SKIPPED` | A static request-shape check could not be evaluated over the v3 collection surface (the request could not be reconstructed from the item IR). | Non-fatal; the runtime contract script still validates the response. Regenerate the collection if it persists. |
332
- | `CONTRACT_COLLECTION_FORMAT_UNSUPPORTED` | A protocol collection builder returned a non-v3 format; only v3/Extensible Collections are created (access-token EC API). | File a bug; the builder must emit v3-ec. No v2 collection is ever created. |
333
- | `CONTRACT_SECURITY_NOT_VALIDATED` | Security requirements were detected but dynamic tests cannot prove auth at runtime. | Run dedicated auth tests and review generated requests for required credentials. |
334
- | `CONTRACT_WEBHOOKS_NOT_VALIDATED` | OpenAPI webhooks were present but are not included in dynamic contract coverage. | Validate webhook behavior separately or model required behavior under `paths`. |
335
- | `CONTRACT_CALLBACKS_NOT_VALIDATED` | Operation callbacks were present but are not included in dynamic contract coverage. | Validate callback behavior separately or add dedicated tests. |
336
- | `CONTRACT_COOKIE_PARAM_NOT_VALIDATED` | A required cookie parameter cannot be included in generated requests, and the runtime test asserts its presence, so the contract run fails until the cookie is supplied at send time. | Attach the cookie via the cookie jar or a `Cookie` header in the run setup, or move the parameter to a header/query location. |
337
- | `CONTRACT_OPERATION_DEPRECATED` | A covered operation is marked `deprecated: true` in the OpenAPI document. | Plan removal of the deprecated operation or drop it from the spec when retired. |
338
- | `CONTRACT_REQUEST_BODY_INCOMPLETE` | A parseable generated request body is missing top-level required properties. | Fix the spec example or regenerate the collection so generated bodies satisfy the request schema. |
339
- | `CONTRACT_READONLY_PROPERTY_IN_REQUEST` | A generated request body includes properties the schema marks `readOnly`. | Remove readOnly properties from request examples; they belong in responses. |
340
- | `CONTRACT_UNDOCUMENTED_QUERY_PARAM` | A generated request sends a query parameter the operation does not declare. | Declare the parameter in the OpenAPI operation or remove it from the generated request. |
341
- | `CONTRACT_LINKS_NOT_VALIDATED` | Response links were present but link traversal is not part of dynamic contract coverage. | Validate linked operation chains with dedicated workflow tests. |
342
- | `CONTRACT_LINKS_PARTIALLY_VALIDATED` | Evaluable link expressions (`$response.body#/...`, `$response.header....`) are asserted at runtime; the remaining expressions (`$request.*`, `$url`, whole-body) are skipped. | Validate the skipped link expressions with dedicated workflow tests. |
343
- | `CONTRACT_UNKNOWN_HTTP_AUTH_SCHEME` | An `http`-type security scheme names an auth scheme outside the IANA HTTP Authentication Scheme registry. | Use a registered scheme name, or ignore if the scheme is intentionally private. |
344
- | `CONTRACT_CREDENTIALS_IN_QUERY` | An `apiKey` security scheme sends credentials in the query string, which leaks into logs and referrers. | Move the credential to a header or cookie. |
345
- | `CONTRACT_SECURITY_SCHEME_URL` | An OAuth2 flow URL or openIdConnect discovery URL is malformed, not HTTPS, or not a discovery-document path. | Fix the URL in `components.securitySchemes`. |
346
- | `CONTRACT_OAUTH2_UNDECLARED_SCOPE` | An operation requires an OAuth2 scope that no flow of the referenced scheme declares. | Add the scope to the flow's `scopes` map or correct the operation's requirement. |
347
- | `CONTRACT_SECURITY_RESPONSES_INCOMPLETE` | A secured operation documents no 401 (or a scoped operation no 403) and no 4XX/default catch-all. | Document the authentication and authorization failure responses. |
348
- | `CONTRACT_UNSECURED_AUTH_RESPONSES` | An operation documents a 401/403 response but declares no security requirement. | Declare the operation's security or remove the auth error responses. |
349
- | `CONTRACT_INVALID_STATUS_CODE` | A declared response key is outside RFC 9110's 100-599, 1XX-5XX, or `default` forms. | Fix the response key in the OpenAPI document. |
350
- | `CONTRACT_BODYLESS_STATUS_WITH_CONTENT` | The spec declares response content for 204/205/304, which RFC 9110 forbids on the wire. | Remove the content declaration or use a different status code. |
351
- | `CONTRACT_METHOD_BODY_SEMANTICS` | A GET/HEAD/DELETE operation declares or sends a request body; RFC 9110 defines no request-body semantics for those methods. | Move the payload to a method with body semantics or drop it. |
352
- | `CONTRACT_PARAM_SERIALIZATION_NOT_VALIDATED` | A parameter declares `allowReserved`, `content`, or a style/explode combination the runtime cannot decode. Exploded `form` arrays and non-exploded `form`/`spaceDelimited`/`pipeDelimited` arrays of scalars are decoded and validated, so they no longer warn; `deepObject` query objects of scalars and `label`/`matrix` path scalars are likewise decoded and validated. | Validate the remaining serialized forms with dedicated tests. |
353
- | `CONTRACT_NONJSON_SCHEMA_NOT_VALIDATED` | A non-JSON response media type declares an object schema that runtime tests cannot validate. | Validate XML or other non-JSON payloads with dedicated tests; Content-Type and body presence are still checked. |
354
- | `CONTRACT_REQUEST_SCHEMA_NOT_VALIDATED` | A JSON request body schema could not be compiled into a runtime request validator. | Simplify the unsupported request schema construct named in the warning. |
355
- | `CONTRACT_SCHEMA_NOT_COMPILED` | One schema could not be compiled by the validator engine, so its runtime check is skipped. | Review the named schema construct; other checks for the operation still run. |
356
- | `CONTRACT_EXAMPLE_SCHEMA_MISMATCH` | A media-type example does not validate against its own schema. | Fix the example or the schema so the spec is self-consistent; generated requests are built from these examples. |
357
- | `CONTRACT_ENCODING_MISMATCH` | A generated form-body field does not match its OpenAPI encoding object: a declared multipart per-part `contentType` is missing or different, a binary-typed field was not generated as a file part, or a field declaring a JSON `contentType` carries an unparseable value. | Regenerate the collection or align the encoding object with the intended part layout. |
358
- | `CONTRACT_ENCODING_HEADERS_NOT_VALIDATED` | A multipart encoding object declares per-part `headers`, which Postman formdata entries cannot carry, so they are not asserted. | Validate per-part headers with dedicated tests if the server depends on them. |
359
- | `CONTRACT_MULTIPART_ENCODING_FIELD_UNKNOWN` | A form-body `encoding` map names a field that is not a property of the request body schema, so the encoding entry can never apply. | Rename the encoding key to a declared schema property or remove it. |
360
- | `CONTRACT_WELL_KNOWN_UNREGISTERED` | A path under `/.well-known/` uses a suffix that is not in the vendored IANA Well-Known URIs registry snapshot (RFC 8615). | Register the suffix, use a registered one, or move the resource out of `/.well-known/`. |
361
- | `CONTRACT_FORM_FIELD_SCHEMA_MISMATCH` | A generated urlencoded or multipart text value does not validate against its scalar property schema. | Fix the spec example feeding the generated body, or correct the property schema. |
362
- | `CONTRACT_DISCRIMINATOR_NOT_VALIDATED` | A `discriminator` has no sibling `oneOf`/`anyOf` of same-spec `$ref` members (typically allOf-parent inheritance), so its dispatch is not validated. | Restructure to the oneOf-plus-discriminator form, or rely on the still-validated composition keywords. |
363
- | `CONTRACT_HEADER_SCHEMA_NOT_VALIDATED` | A response header declares an object or otherwise undecodable schema, so its serialized value is checked for presence only. Arrays of scalars are split on commas and validated. | Use a scalar or array-of-scalars header schema, or validate the serialized header form with dedicated tests. |
364
- | `CONTRACT_PATH_PARAM_NOT_VALIDATED` | A path parameter declares a non-scalar schema or a serialization the runtime cannot decode, so its value is not validated. Scalar path parameters are validated at runtime against the resolved path segment. | Use a scalar path schema, or validate path value semantics with dedicated tests. |
365
- | `CONTRACT_PATH_PARAM_COMPOUND_SEGMENT_NOT_VALIDATED` | A path parameter is embedded in a compound path segment (for example `/files/{name}.{ext}`), so its value cannot be extracted from the sent path and its schema is not validated at runtime. | Split the compound segment into its own path parameter, or validate the value semantics with a dedicated test. |
366
- | `CONTRACT_DUPLICATE_OPERATION_MATCH` | Multiple OpenAPI operations share the same canonical request mapping candidate. | Disambiguate paths, server prefixes, or templated routes. |
367
- | `CONTRACT_DUPLICATE_OPERATION_REQUEST` | More than one generated request mapped to the same contract operation. | Disambiguate paths/operations or generated requests. |
368
- | `CONTRACT_OPERATION_COVERAGE_FAILED` | Generated contract collection did not cover every eligible operation. | Regenerate the collection or fix operation paths. |
369
- | `CONTRACT_FORBIDDEN_SCRIPT_CONSTRUCT` | Generated script included a forbidden dynamic validation construct. | Report the schema that triggered unsafe generation. |
370
- | `CONTRACT_SCRIPT_SIZE_EXCEEDED` | A generated request test script exceeded the per-script size gate. | Reduce schema complexity or split the API. |
371
- | `CONTRACT_COLLECTION_SIZE_EXCEEDED` | Instrumented contract collection exceeded the size gate. | Reduce schema/operation count or split the API. |
372
- | `CONTRACT_COLLECTION_ID_COLLISION` | Baseline, smoke, and contract IDs were not pairwise distinct. | Pass distinct collection IDs or clear stale IDs. |
373
- | `CONTRACT_PLAN_MISSING` | Contract instrumentation ran without a preflight-generated contract plan. | Rerun with dynamic contract preflight enabled and report the failure if it persists. |
374
- | `CONTRACT_SPEC_ROLLBACK_FAILED` | Best-effort previous spec restoration failed after a later error. | Restore the previous spec content manually using the emitted SHA-256. |
375
-
376
- ## Resources
284
+ | Postman CLI `spec lint` | Bootstrap | Fails the run on lint errors (PMAK-gated) |
285
+ | Static document lints | Bootstrap | Warnings only: spec-shape defects and runtime-coverage disclosures, logged and never fatal |
286
+ | Runtime contract tests | Every CI collection run | `pm.test()` pass/fail against the live response |
287
+
288
+ ```mermaid
289
+ flowchart LR
290
+ SPEC["OpenAPI spec"] --> IDX["buildContractIndex()"]
291
+ IDX --> LINT["static lints -> warnings<br/>in the bootstrap log"]:::warn
292
+ IDX --> OPS["structured contract"]
293
+ OPS --> TESTS["pm.test() scripts injected<br/>into generated collections"]:::inject
294
+ TESTS --> RUN["postman collection run<br/>(repo-sync CI workflow)"]
295
+ RUN --> LIVE["live API or mock<br/>pass/fail per assertion"]:::inject
296
+ classDef warn fill:#7f1d1d,color:#fff,stroke:#ef4444
297
+ classDef inject fill:#14532d,color:#fff,stroke:#4ade80
298
+ ```
377
299
 
378
- ### The suite
300
+ Static lints catch the spec lying (a HEAD operation declaring a body, a 304 on a POST); runtime tests catch the server lying (a 200 where only 201 is declared, a body that fails its schema). Bootstrap-time failures use `CONTRACT_*` codes and stop the run before durable collections are overwritten; warnings are logged and never gate the run.
379
301
 
380
- | Action | Role |
381
- | --- | --- |
382
- | [Postman API Onboarding](https://github.com/postman-cs/postman-api-onboarding-action) | Entry point: chains workspace bootstrap, repo sync, and optional Insights linking |
383
- | [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action) | Mints the service-account access token and team ID |
384
- | [Postman Onboarding: AWS Spec Discovery](https://github.com/postman-cs/postman-aws-spec-discovery-action) | Discovers and exports API specs from AWS services |
385
- | [Postman Onboarding: Workspace Bootstrap](https://github.com/postman-cs/postman-bootstrap-action) | Creates the workspace, uploads the spec, generates collections |
386
- | [Postman Onboarding: Smoke Flow](https://github.com/postman-cs/postman-smoke-flow-action) | Applies a curated flow.yaml to the Smoke collection |
387
- | [Postman Onboarding: Repo Sync](https://github.com/postman-cs/postman-repo-sync-action) | Exports artifacts into the repo and wires CI, mocks, and monitors |
388
- | [Postman Onboarding: Insights Linking](https://github.com/postman-cs/postman-insights-onboarding-action) | Links Insights discovered services to the workspace |
302
+ Representative codes:
389
303
 
390
- Sibling actions in the Postman onboarding pipeline:
304
+ | Error code | Layer | Effect | Meaning |
305
+ | --- | --- | --- | --- |
306
+ | `CONTRACT_SPEC_VALIDATION_FAILED` | Spec loading | Fails the run | The bundled document failed OpenAPI validation |
307
+ | `CONTRACT_OPERATION_COVERAGE_FAILED` | Instrumentation | Fails the run | Generated collection did not cover every eligible operation |
308
+ | `CONTRACT_HEAD_RESPONSE_BODY` | Static lint | Warning | A HEAD operation declares response content (RFC 9110) |
309
+ | `CONTRACT_SCHEMA_NOT_COMPILED` | Disclosure | Warning | One schema could not be compiled; its runtime check is skipped and disclosed |
391
310
 
392
- - [postman-cs/postman-api-onboarding-action](https://github.com/postman-cs/postman-api-onboarding-action): composite action that orchestrates the pipeline
393
- - [postman-cs/postman-resolve-service-token-action](https://github.com/postman-cs/postman-resolve-service-token-action): mints a service-account access token and team ID
394
- - [postman-cs/postman-aws-spec-discovery-action](https://github.com/postman-cs/postman-aws-spec-discovery-action): discovers AWS APIs and specs
395
- - [postman-cs/postman-smoke-flow-action](https://github.com/postman-cs/postman-smoke-flow-action): applies a curated flow.yaml to the Smoke collection
396
- - [postman-cs/postman-repo-sync-action](https://github.com/postman-cs/postman-repo-sync-action): syncs artifacts, environments, mocks, and monitors
397
- - [postman-cs/postman-insights-onboarding-action](https://github.com/postman-cs/postman-insights-onboarding-action): links Insights to the workspace
311
+ The complete catalog of all 142 codes, grouped by layer with per-code remediation, is in [Contract Error Codes](docs/contract-error-codes.md).
398
312
 
399
- Package and docs:
313
+ ## Resources
400
314
 
401
315
  - npm package: [@postman-cse/onboarding-bootstrap](https://www.npmjs.com/package/@postman-cse/onboarding-bootstrap)
402
- - [Credential matrix](docs/credentials.md)
403
- - [Support](SUPPORT.md)
404
- - [Security Policy](SECURITY.md)
405
- - [Release Policy](RELEASE_POLICY.md)
406
- - Postman API and auth references: [Postman API](https://learning.postman.com/docs/reference/postman-api/intro-api/), [API authentication](https://learning.postman.com/docs/reference/postman-api/authentication/), [service accounts](https://learning.postman.com/docs/administration/service-accounts/), [EU data residency](https://learning.postman.com/docs/administration/enterprise/about-eu-data-residency/)
407
- - Postman design resources: [workspaces](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/overview/), [Spec Hub](https://learning.postman.com/docs/design-apis/specifications/overview/), [import a specification](https://learning.postman.com/docs/design-apis/specifications/import-a-specification/), [generate collections](https://learning.postman.com/docs/design-apis/specifications/generate-collections/), [validate a specification](https://learning.postman.com/docs/design-apis/specifications/validate-a-specification/)
408
- - Postman execution resources: [Postman CLI collection runs](https://learning.postman.com/docs/postman-cli/postman-cli-collections/), [Postman CLI governance](https://learning.postman.com/docs/postman-cli/postman-cli-governance/), [API governance rules](https://learning.postman.com/docs/api-governance/configurable-rules/configuring-api-governance-rules/), [mock servers](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/), [monitors](https://learning.postman.com/docs/monitoring-your-api/intro-monitors/)
409
- - Local development: `npm install`, `npm test`, `npm run typecheck`, `npm run build` (produces the committed `dist/` bundles used by `action.yml`); regenerate the Inputs and Outputs tables with `npm run docs:tables`
316
+ - Docs in this repo: [credentials](docs/credentials.md), [spec handling](docs/spec-handling.md), [lifecycle modes](docs/lifecycle-and-operations.md), [team identity](docs/team-identity.md), [generated assertions](docs/generated-assertions.md), [contract error codes](docs/contract-error-codes.md)
317
+ - Marketplace docs: [Support](SUPPORT.md), [Security Policy](SECURITY.md), [Release Policy](RELEASE_POLICY.md)
318
+ - Postman references: [Postman API](https://learning.postman.com/docs/reference/postman-api/intro-api/), [API authentication](https://learning.postman.com/docs/reference/postman-api/authentication/), [service accounts](https://learning.postman.com/docs/administration/service-accounts/), [Spec Hub](https://learning.postman.com/docs/design-apis/specifications/overview/), [generate collections](https://learning.postman.com/docs/design-apis/specifications/generate-collections/), [Postman CLI governance](https://learning.postman.com/docs/postman-cli/postman-cli-governance/)
410
319
 
411
- ## Telemetry
320
+ Local development: `npm install`, `npm test`, `npm run typecheck`, `npm run build` (produces the committed `dist/` bundles used by `action.yml`).
412
321
 
413
- This action sends a single non-identifying usage event when a run completes, so the
414
- Postman team can measure adoption across CI systems. The event contains the
415
- action name and version, your Postman team ID, the detected CI provider and
416
- runner kind, the run outcome, the CI run identifier, an event timestamp, and a one-way SHA-256 hash of the repository
417
- identifier. Each event also carries a schema version and a constant event marker (always `completion`). The Postman team ID is sent in the clear on a legitimate-interest
418
- basis to measure product adoption.
419
-
420
- The `events.pm-cse.dev` endpoint is operated by the Postman Customer Success
421
- Engineering team. Postman, Inc. processes these events only to measure
422
- onboarding adoption in aggregate, retains them only as aggregated counts for
423
- product-adoption trend analysis, and includes no payload field that identifies
424
- an individual person.
425
-
426
- It never sends API keys, access tokens, spec content, workspace or repository
427
- names, or any personal data. It is fire-and-forget with a hard
428
- timeout and can never block or fail your pipeline. Corporate HTTP and HTTPS
429
- proxies are honored through the standard `HTTPS_PROXY`, `HTTP_PROXY`, and
430
- `NO_PROXY` environment variables.
431
-
432
- Disable it by setting either environment variable in your CI:
433
-
434
- ```sh
435
- POSTMAN_ACTIONS_TELEMETRY=off
436
- # or the cross-tool standard
437
- DO_NOT_TRACK=1
438
- ```
439
-
440
- Telemetry is also skipped automatically when no Postman team ID can be resolved.
322
+ ## Telemetry
441
323
 
442
- Events are sent over HTTPS to `https://events.pm-cse.dev/v1/events`. To
443
- allowlist this destination on a restricted network, or to route events to a
444
- collector you operate, set the `POSTMAN_ACTIONS_TELEMETRY_ENDPOINT` environment
445
- variable to your own URL.
324
+ The action sends one anonymous usage event per run (action name/version, outcome, coarse CI metadata; never secrets, spec content, or repo names). Disable with `POSTMAN_ACTIONS_TELEMETRY=off` or `DO_NOT_TRACK=1`; route events to your own collector with `POSTMAN_ACTIONS_TELEMETRY_ENDPOINT`.
446
325
 
447
326
  ## License
448
327