@postman-cse/onboarding-bootstrap 1.2.3 → 2.0.0

package/README.md

@@ -36,11 +36,11 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - id: postman_token
-        uses: postman-cs/postman-resolve-service-token-action@v1
+        uses: postman-cs/postman-resolve-service-token-action@v2
         with:
           postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
           postman-region: us
-      - uses: postman-cs/postman-bootstrap-action@v1
+      - uses: postman-cs/postman-bootstrap-action@v2
         with:
           project-name: core-payments
           spec-url: https://raw.githubusercontent.com/postman-cs/postman-bootstrap-action/main/examples/core-payments-openapi.yaml
@@ -50,7 +50,7 @@ jobs:
           credential-preflight: enforce
 ```
 
-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. Use a [Postman service account](https://learning.postman.com/docs/administration/service-accounts/) PMAK for `postman-api-key`; the service-token action is the primary way to mint the `postman-access-token` used for governance, cloud sync, and canonical workspace validation. See [Obtaining Credentials](docs/credentials.md) for the credential matrix and legacy fallback.
+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.
 
 ## Common scenarios
 
@@ -60,7 +60,7 @@ For Git-first workflows, read the OpenAPI document directly from the checked-out
 
 ```yaml
 - uses: actions/checkout@v5
-- uses: postman-cs/postman-bootstrap-action@v1
+- uses: postman-cs/postman-bootstrap-action@v2
   with:
     project-name: core-payments
     spec-path: apis/core-payments/openapi.yaml
@@ -72,7 +72,7 @@ For Git-first workflows, read the OpenAPI document directly from the checked-out
 Pass `workspace-id`, `spec-id`, and existing collection IDs to rerun without creating duplicate Postman assets. When `.postman/resources.yaml` is committed on the checked-out ref, the action reuses its workspace, spec, and collection mappings automatically.
 
 ```yaml
-- uses: postman-cs/postman-bootstrap-action@v1
+- uses: postman-cs/postman-bootstrap-action@v2
   with:
     project-name: core-payments
     workspace-id: ws-123
@@ -89,7 +89,7 @@ Pass `workspace-id`, `spec-id`, and existing collection IDs to rerun without cre
 Create a release-scoped spec and collection set instead of refreshing the canonical assets in place:
 
 ```yaml
-- uses: postman-cs/postman-bootstrap-action@v1
+- uses: postman-cs/postman-bootstrap-action@v2
   with:
     project-name: core-payments
     spec-url: https://raw.githubusercontent.com/postman-cs/postman-bootstrap-action/main/examples/core-payments-openapi.yaml
@@ -109,7 +109,7 @@ Compare the incoming contract before any Postman mutation. `pr-native` mode diff
 - uses: actions/checkout@v5
   with:
     fetch-depth: 0
-- uses: postman-cs/postman-bootstrap-action@v1
+- uses: postman-cs/postman-bootstrap-action@v2
   with:
     project-name: core-payments
     spec-path: apis/core-payments/openapi.yaml
@@ -127,12 +127,12 @@ Set the repository custom property `postman-governance-group`, then provide toke
 
 ```yaml
 - id: postman-token
-  uses: postman-cs/postman-resolve-service-token-action@v1
+  uses: postman-cs/postman-resolve-service-token-action@v2
   with:
     postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
     postman-region: us
 
-- uses: postman-cs/postman-bootstrap-action@v1
+- uses: postman-cs/postman-bootstrap-action@v2
   with:
     project-name: core-payments
     spec-url: https://raw.githubusercontent.com/postman-cs/postman-bootstrap-action/main/examples/core-payments-openapi.yaml
@@ -149,7 +149,7 @@ For one-off runs, `governance-group` can be passed directly and overrides the re
 Postman organizations with multiple sub-teams require an explicit `workspace-team-id` for workspace creation:
 
 ```yaml
-- uses: postman-cs/postman-bootstrap-action@v1
+- uses: postman-cs/postman-bootstrap-action@v2
   with:
     project-name: core-payments
     spec-url: https://raw.githubusercontent.com/postman-cs/postman-bootstrap-action/main/examples/core-payments-openapi.yaml
@@ -169,6 +169,7 @@ See [Team Identity](docs/team-identity.md) for sub-team discovery and team-ID de
 | `baseline-collection-id` | Existing baseline collection ID | no |  |
 | `smoke-collection-id` | Existing smoke collection ID | no |  |
 | `contract-collection-id` | Existing contract collection ID | no |  |
+| `additional-collections-dir` | Workspace-relative directory containing curated Postman collection JSON/YAML files to create or update in the workspace. | no |  |
 | `sync-examples` | Whether linked spec/collection relations should enable example syncing | no | `true` |
 | `collection-sync-mode` | Collection lifecycle policy (refresh or version) | no | `refresh` |
 | `spec-sync-mode` | Spec lifecycle policy (update or version) | no | `update` |
@@ -179,9 +180,11 @@ See [Team Identity](docs/team-identity.md) for sub-team discovery and team-ID de
 | `governance-group` | Postman governance workspace group name. Overrides the postman-governance-group repository custom property and domain mapping. | no |  |
 | `requester-email` | Requester email for audit context | no |  |
 | `workspace-admin-user-ids` | Comma-separated workspace admin user ids | no |  |
-| `workspace-team-id` | Numeric sub-team ID for org-mode workspace creation. Required when the API key belongs to an org with multiple sub-teams. Run the action without this input to see available sub-teams listed in the error output. | no |  |
+| `workspace-team-id` | Numeric sub-team ID for org-mode workspace creation. Required when your Postman team is an org with multiple sub-teams. Run the action without this input to see available sub-teams listed in the error output. | no |  |
 | `spec-url` | HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path. | no |  |
 | `spec-path` | Local filesystem path to the OpenAPI document (relative to the workspace). Provide either spec-url or spec-path. | no |  |
+| `protocol` | API spec protocol. auto (default) detects from content/extension. openapi flows through Spec Hub; graphql (SDL/introspection), grpc (.proto), and soap (WSDL) build and instrument a Postman collection directly. | no | `auto` |
+| `protocol-endpoint-url` | Endpoint URL/authority used by generated non-OpenAPI requests (e.g. {{baseUrl}}/graphql, grpc://host:port). Supports Postman variable interpolation. Ignored for openapi. | no |  |
 | `openapi-version` | OpenAPI specification version override (3.0 or 3.1). When not set, the version is auto-detected from the spec content. | no |  |
 | `breaking-change-mode` | OpenAPI breaking-change comparison mode (off, pr-native, baseline-only, or previous-spec) | no | `off` |
 | `breaking-baseline-spec-path` | Workspace-relative baseline OpenAPI spec path used by baseline-only mode and pr-native fallback | no |  |
@@ -192,8 +195,8 @@ See [Team Identity](docs/team-identity.md) for sub-team discovery and team-ID de
 | `governance-mapping-json` | Legacy JSON map of business domain to governance group name. Prefer governance-group or the postman-governance-group repository custom property. | no | `{}` |
 | `github-token` | GitHub token used to read the postman-governance-group repository custom property | no |  |
 | `gh-fallback-token` | Fallback GitHub token used to read repository custom properties when github-token cannot | no |  |
-| `postman-api-key` | Postman API key used for bootstrap operations | yes |  |
-| `postman-access-token` | Postman access token used for governance and workspace mutations | no |  |
+| `postman-api-key` | Postman service-account API key (PMAK). With a postman-access-token present, the PMAK is used ONLY to mint/re-mint the access token and to log in the Postman CLI for `spec lint` — never for an asset operation. When the key is absent, the CLI spec lint is skipped (governance errors are not enforced). Optional. | no |  |
+| `postman-access-token` | Postman service-account access token (x-access-token). Primary credential — every asset operation (workspace create/visibility, spec upload/update, collection generation/read/mutation, test injection, tagging, team-scope) runs through the access-token gateway. Mint it with postman-resolve-service-token-action. Optional only for legacy PMAK-only runs; supply it for the gateway path. | no |  |
 | `credential-preflight` | Credential identity preflight policy. warn (default) logs a note and continues when postman-api-key and postman-access-token resolve to different parent orgs; enforce fails the run on that condition before any workspace is created. | no | `warn` |
 | `folder-strategy` | Folder organization strategy for generated collections (Paths or Tags) | no | `Paths` |
 | `nested-folder-hierarchy` | When folder-strategy is Tags, enables nested folder hierarchy | no | `false` |
@@ -214,7 +217,7 @@ See [Team Identity](docs/team-identity.md) for sub-team discovery and team-ID de
 | `smoke-collection-id` | Smoke collection ID | n/a | n/a |
 | `contract-collection-id` | Contract collection ID | n/a | n/a |
 | `collections-json` | JSON summary of generated collections | n/a | n/a |
-| `lint-summary-json` | JSON summary of lint errors and warnings | n/a | n/a |
+| `lint-summary-json` | JSON summary of lint errors and warnings. When postman-api-key is absent the CLI lint is skipped and this is { status: "skipped", reason: "no postman-api-key" }. | n/a | n/a |
 | `breaking-change-status` | OpenAPI breaking-change check status | n/a | n/a |
 | `breaking-change-summary-json` | JSON summary of the OpenAPI breaking-change check | n/a | n/a |
 <!-- outputs-table:end -->
@@ -286,11 +289,12 @@ steps:
 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.
 
 - **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).
-- **Team identity:** the parent team ID is derived from `postman-api-key`; org-mode tenants pass `workspace-team-id` for the sub-team that should own the workspace. See [Team Identity](docs/team-identity.md).
+- **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).
 - **Git providers:** workspace-to-repository linking supports GitHub and GitLab, cloud and self-hosted. See [Git Provider Support](docs/git-provider-support.md).
 - **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).
 - **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).
-- **Credentials:** `postman-api-key` handles standard Postman API operations; the optional `postman-access-token` unlocks governance assignment, cloud link/sync, and canonical workspace validation. See [Obtaining Credentials](docs/credentials.md).
+- **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).
+- **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). Creating the gRPC collection and running it in CI are separate gates: execution additionally needs the `grpc_protocol_execution_allowed` account feature flag in Postman CLI. See [Multi-Protocol Contract Assertions](docs/MULTIPROTOCOL-ASSERTIONS.md).
 
 ## Dynamic contract tests
 
@@ -319,6 +323,8 @@ Dynamic contract failures and warnings use `CONTRACT_` error codes. Remediation
 | `CONTRACT_UNSUPPORTED_SCHEMA_DIALECT` | A schema declared an unsupported JSON Schema dialect. | Use draft-07 or 2020-12-compatible schemas. |
 | `CONTRACT_SCHEMA_COMPILE_FAILED` | schemasafe could not compile a response/header schema. | Simplify or correct the unsupported schema. |
 | `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. |
+| `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. |
+| `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. |
 | `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. |
 | `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`. |
 | `CONTRACT_CALLBACKS_NOT_VALIDATED` | Operation callbacks were present but are not included in dynamic contract coverage. | Validate callback behavior separately or add dedicated tests. |

package/action.yml

@@ -21,6 +21,9 @@ inputs:
   contract-collection-id:
     description: Existing contract collection ID
     required: false
+  additional-collections-dir:
+    description: Workspace-relative directory containing curated Postman collection JSON/YAML files to create or update in the workspace.
+    required: false
   sync-examples:
     description: Whether linked spec/collection relations should enable example syncing
     required: false
@@ -56,8 +59,8 @@ inputs:
     required: false
   workspace-team-id:
     description: >-
-      Numeric sub-team ID for org-mode workspace creation. Required when the
-      API key belongs to an org with multiple sub-teams. Run the action without
+      Numeric sub-team ID for org-mode workspace creation. Required when your
+      Postman team is an org with multiple sub-teams. Run the action without
       this input to see available sub-teams listed in the error output.
     required: false
   spec-url:
@@ -66,6 +69,14 @@ inputs:
   spec-path:
     description: Local filesystem path to the OpenAPI document (relative to the workspace). Provide either spec-url or spec-path.
     required: false
+  protocol:
+    description: API spec protocol. auto (default) detects from content/extension. openapi flows through Spec Hub; graphql (SDL/introspection), grpc (.proto), and soap (WSDL) build and instrument a Postman collection directly.
+    required: false
+    default: auto
+  protocol-endpoint-url:
+    description: Endpoint URL/authority used by generated non-OpenAPI requests (e.g. {{baseUrl}}/graphql, grpc://host:port). Supports Postman variable interpolation. Ignored for openapi.
+    required: false
+    default: ''
   openapi-version:
     description: OpenAPI specification version override (3.0 or 3.1). When not set, the version is auto-detected from the spec content.
     required: false
@@ -103,10 +114,10 @@ inputs:
     description: Fallback GitHub token used to read repository custom properties when github-token cannot
     required: false
   postman-api-key:
-    description: Postman API key used for bootstrap operations
-    required: true
+    description: Postman service-account API key (PMAK). With a postman-access-token present, the PMAK is used ONLY to mint/re-mint the access token and to log in the Postman CLI for `spec lint` — never for an asset operation. When the key is absent, the CLI spec lint is skipped (governance errors are not enforced). Optional.
+    required: false
   postman-access-token:
-    description: Postman access token used for governance and workspace mutations
+    description: Postman service-account access token (x-access-token). Primary credential — every asset operation (workspace create/visibility, spec upload/update, collection generation/read/mutation, test injection, tagging, team-scope) runs through the access-token gateway. Mint it with postman-resolve-service-token-action. Optional only for legacy PMAK-only runs; supply it for the gateway path.
     required: false
   credential-preflight:
     description: "Credential identity preflight policy. warn (default) logs a note and continues when postman-api-key and postman-access-token resolve to different parent orgs; enforce fails the run on that condition before any workspace is created."
@@ -153,7 +164,7 @@ outputs:
   collections-json:
     description: JSON summary of generated collections
   lint-summary-json:
-    description: JSON summary of lint errors and warnings
+    description: 'JSON summary of lint errors and warnings. When postman-api-key is absent the CLI lint is skipped and this is { status: "skipped", reason: "no postman-api-key" }.'
   breaking-change-status:
     description: OpenAPI breaking-change check status
   breaking-change-summary-json: