@postman-cs/onboarding-api 3.5.11 → 3.5.13

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 (3) hide show
  1. package/README.md +45 -15
  2. package/action.yml +19 -5
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,14 +1,20 @@
1
- # Postman API Onboarding
1
+ # Postman Enterprise Automation: API Onboarding
2
2
 
3
3
  [![CI](https://github.com/postman-cs/postman-api-onboarding-action/actions/workflows/ci.yml/badge.svg)](https://github.com/postman-cs/postman-api-onboarding-action/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/postman-cs/postman-api-onboarding-action?sort=semver)](https://github.com/postman-cs/postman-api-onboarding-action/releases) [![npm](https://img.shields.io/npm/v/%40postman-cs%2Fonboarding-api)](https://www.npmjs.com/package/@postman-cs/onboarding-api) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
4
4
 
5
- Canonical entrypoint for the Postman API Onboarding suite. Use this composite action when a GitHub repository needs the full onboarding path: workspace bootstrap, OpenAPI upload, collection generation, repository artifact sync, built-in smoke and contract runs, and optional Postman Insights linking.
5
+ Canonical entrypoint for the Postman Enterprise Automation Suite. Use this composite action when a GitHub repository needs the full onboarding path: workspace bootstrap, OpenAPI upload, collection generation, repository artifact sync, built-in smoke and contract runs, and optional Postman Insights linking.
6
6
 
7
7
  > **The pipeline leaves executable, standards-grounded tests behind, not just assets.** Bootstrap injects spec-derived contract assertions into the `[Contract]` collection, the Smoke collection carries generated smoke scripts, and repo-sync writes a CI workflow that reruns both with the Postman CLI on every push, pull request, and schedule. Full inventories: [Generated assertions](https://github.com/postman-cs/postman-bootstrap-action/blob/main/docs/generated-assertions.md), [Smoke generated tests](https://github.com/postman-cs/postman-smoke-flow-action/blob/main/docs/generated-tests.md), and [Contract Enforcement Layers](https://github.com/postman-cs/postman-bootstrap-action/blob/main/docs/contract-enforcement-layers.md).
8
8
 
9
9
  ## Quick start
10
10
 
11
- This workflow is the happy path for a new API repository. It mints a service-account access token and team ID with [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action), then feeds those outputs into this composite action. The OpenAPI fixture is public, so the workflow is paste-runnable after `POSTMAN_API_KEY` is configured.
11
+ This workflow onboards a new API repository using a public OpenAPI fixture. It mints a service-account access token and team ID with [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action), then passes those outputs to this action.
12
+
13
+ Before running it:
14
+
15
+ - Configure `POSTMAN_API_KEY` and verify the workspace permissions below.
16
+ - The default run commits and pushes generated files to the checked-out branch. For a protected branch, use the [pull-request workflow](docs/protected-branch-workflows.md). Set `repo-write-mode: none` to leave generated files on the runner without committing them; Postman-side provisioning still runs.
17
+ - For a service folder, use the [monorepo inputs](#monorepos) instead of repository-root paths. Set `generate-ci-workflow: 'false'` if your repository already owns its test workflow.
12
18
 
13
19
  ### Workspace-creation preflight
14
20
 
@@ -60,11 +66,17 @@ That run creates or reuses a [Postman workspace](https://learning.postman.com/do
60
66
 
61
67
  Use `postman-region: eu` for [EU data residency](https://learning.postman.com/docs/administration/enterprise/about-eu-data-residency/). Keep the same region on the service-token step and the composite action.
62
68
 
69
+ ### Read the result
70
+
71
+ Use `workspace-url` to open the workspace and `commit-sha` to identify the generated commit, when one was created. The `bootstrap-outcome`, `smoke-flow-outcome`, `repo-sync-outcome`, and `insights-outcome` outputs identify each phase's runner outcome; optional phases can be skipped.
72
+
73
+ The built-in smoke and contract runs are warning-only. A successful onboarding step does **not** prove the API tests passed. Inspect the test-step logs and `postman-test-results` JUnit artifact. To make test failures fail your workflow, [defer the built-in tests and run them in a strict caller step](docs/deferred-tests.md).
74
+
63
75
  ## Which action should I use?
64
76
 
65
77
  | Scenario | Start with | Why |
66
78
  | --- | --- | --- |
67
- | Full GitHub onboarding from an OpenAPI spec | [Postman API Onboarding](https://github.com/postman-cs/postman-api-onboarding-action) | Canonical suite entrypoint. Chains bootstrap, repo sync, tests, and optional Insights. |
79
+ | Full GitHub onboarding from an OpenAPI spec | [Postman Enterprise Automation: API Onboarding](https://github.com/postman-cs/postman-api-onboarding-action) | Canonical suite entrypoint. Chains bootstrap, repo sync, tests, and optional Insights. |
68
80
  | Mint an access token and resolve team ID | [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action) | Primary credential path for this composite action. Run it before onboarding. |
69
81
  | Discover an OpenAPI spec from AWS | [Postman Onboarding: AWS Spec Discovery](https://github.com/postman-cs/postman-aws-spec-discovery-action) | Produces a spec URL or artifact that can feed this composite action. |
70
82
  | Provision only the Postman workspace and collections | [Postman Onboarding: Workspace Bootstrap](https://github.com/postman-cs/postman-bootstrap-action) | Lower-level action for custom pipelines that do not want repo sync. |
@@ -76,6 +88,23 @@ Use `postman-region: eu` for [EU data residency](https://learning.postman.com/do
76
88
 
77
89
  Use one dispatcher under the repository-root `.github/workflows/` directory; GitHub ignores workflow files inside service directories. Set `working-directory: services/<service>` on the composite so relative spec and flow paths, `postman/` exports, and `.postman/` state stay inside that service. Each service should use its own `project-name` and Postman workspace by default.
78
90
 
91
+ Set `working-directory` under the action's `with:` block. GitHub's `defaults.run.working-directory` only affects shell steps. For a checked-out file at `services/payments/openapi.yaml`, use:
92
+
93
+ ```yaml
94
+ - uses: postman-cs/postman-api-onboarding-action@v3
95
+ with:
96
+ working-directory: services/payments
97
+ project-name: payments
98
+ spec-path: openapi.yaml
99
+ generate-ci-workflow: 'false'
100
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
101
+ github-token: ${{ github.token }}
102
+ ```
103
+
104
+ Both `spec-path` and `flow-path` are relative to `working-directory` when it's set, otherwise to the repository root. The example writes artifacts to `services/payments/postman/` and state to `services/payments/.postman/`. No `artifact-directory` input is needed or exposed by this action.
105
+
106
+ If you see `spec-path does not name a file under GITHUB_WORKSPACE`, check that you haven't repeated the service prefix. With the example above, `spec-path: services/payments/openapi.yaml` would look for `services/payments/services/payments/openapi.yaml`. The error's “repository-relative” wording refers to the repository root only when `working-directory` is omitted. Also check that the file exists in the checked-out revision with the exact filename and case.
107
+
79
108
  When `working-directory` is omitted, `generate-ci-workflow` still defaults to `true`. With a service directory it defaults to `false`, and explicitly requesting `true` fails because the nested workflow would not run. Start with [`examples/monorepo-dispatcher.yml`](examples/monorepo-dispatcher.yml), which detects changed services, serializes onboarding commits, prevents generated-artifact loops, and runs service collections in parallel. The canonical layout and CLI alternative are in the [repo-sync monorepo guide](https://github.com/postman-cs/postman-repo-sync-action/blob/main/docs/monorepo.md).
80
109
 
81
110
  ## Scenario guide
@@ -92,13 +121,13 @@ When `working-directory` is omitted, `generate-ci-workflow` still defaults to `t
92
121
 
93
122
  ## Credentials and region
94
123
 
95
- Run `postman-resolve-service-token-action` first and pass its `token` and `team-id` outputs as `postman-access-token` and `postman-team-id`: the access token is the primary credential, carrying every Postman asset operation in the wrapped actions through the access-token gateway. The `postman-api-key` PMAK mints and re-mints that token and authenticates the Postman CLI logins (bootstrap spec lint, repo-sync generated-CI collection run). `github-token` (and optionally `gh-fallback-token`) handles repository writes, and `credential-preflight: enforce` fails before workspace creation when the PMAK and access token resolve to different parent orgs. Detailed setup and the legacy fallback: [docs/credentials.md](docs/credentials.md).
124
+ Run `postman-resolve-service-token-action` first and pass its `token` and `team-id` outputs as `postman-access-token` and `postman-team-id`: the access token is the primary credential, carrying every Postman asset operation in the wrapped actions through the access-token gateway. The `postman-api-key` PMAK mints and re-mints that token and authenticates the Postman CLI logins (the built-in smoke/contract test run, repo-sync generated-CI collection run). `github-token` (and optionally `gh-fallback-token`) handles repository writes, and `credential-preflight: enforce` fails before workspace creation when the PMAK and access token resolve to different parent orgs. Detailed setup and the legacy fallback: [docs/credentials.md](docs/credentials.md).
96
125
 
97
126
  ### Authentication matrix
98
127
 
99
128
  | Credential or permission | Where it appears | Required for | Source and permissions | Expiration behavior |
100
129
  | --- | --- | --- | --- | --- |
101
- | Service-account PMAK | `POSTMAN_API_KEY`, or `POSTMAN_SERVICE_ACCOUNT_API_KEY` in AWS examples | Access-token minting and the Postman CLI logins inside the wrapped actions (bootstrap spec lint, repo-sync generated-CI collection run) | GitHub secret backed by a [Postman service account](https://learning.postman.com/docs/administration/service-accounts/) API key | Long-lived until rotated in Postman and updated in CI |
130
+ | Service-account PMAK | `POSTMAN_API_KEY`, or `POSTMAN_SERVICE_ACCOUNT_API_KEY` in AWS examples | Access-token minting and the Postman CLI logins inside the wrapped actions (the built-in smoke/contract test run, repo-sync generated-CI collection run) | GitHub secret backed by a [Postman service account](https://learning.postman.com/docs/administration/service-accounts/) API key | Long-lived until rotated in Postman and updated in CI |
102
131
  | Generated access token | `steps.postman-token.outputs.token`, passed as `postman-access-token` | Every Postman asset operation in bootstrap and repo sync, routed through the access-token gateway (workspace, spec, collection, environment, mock, monitor, tagging, identity) | Minted by `postman-resolve-service-token-action` from the service-account PMAK | Fresh per workflow run; avoid storing unless a scheduled refresh workflow intentionally writes `POSTMAN_ACCESS_TOKEN` |
103
132
  | Human-user Insights credentials | `insights-postman-api-key`, `insights-postman-access-token` | Optional Insights linking only | A human workspace-admin user's PMAK and session access token, stored as separate GitHub secrets | Required together only when `enable-insights: true` and `onboarding-scope: full`; never substitute the service-account suite credentials |
104
133
  | Team ID | `postman-team-id`: `steps.postman-token.outputs.team-id` (parent/org team id for integration context). `workspace-team-id`: optional explicit squad id for org-mode workspace creation | `postman-team-id` supplies org-mode integration header context. `workspace-team-id` selects the sub-team that owns a new workspace; the resolver `team-id` output is a parent/org id and must never be substituted for `workspace-team-id` | `postman-team-id` from `postman-resolve-service-token-action`. `workspace-team-id` from a known squad id when bootstrap cannot infer one | Not secrets and do not expire; update if the parent org or target squad changes |
@@ -265,6 +294,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
265
294
  | `onboarding-scope` | Onboarding scope. Use full for the complete pipeline or spec-only for workspace/spec onboarding without generated assets. | no | `full` |
266
295
  | `sync-examples` | Whether linked spec/collection relations should enable example syncing. | no | `true` |
267
296
  | `collection-sync-mode` | Collection lifecycle policy (refresh or version). Default refresh ensures tracked collections stay in sync with the spec. | no | `refresh` |
297
+ | `collection-update-strategy` | Collection update strategy (auto or whole). Default whole preserves full collection updates. | no | `whole` |
268
298
  | `spec-sync-mode` | Spec lifecycle policy (update or version). | no | `update` |
269
299
  | `release-label` | Optional release label for versioned specs and collections. When omitted during versioned sync, derived from GitHub tag or branch metadata. | no | |
270
300
  | `monitor-id` | Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one. | no | |
@@ -284,7 +314,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
284
314
  | `workspace-admin-user-ids` | Comma-separated workspace admin user ids. | no | |
285
315
  | `workspace-team-id` | Numeric SUB-TEAM (squad) id that should own the created org-mode workspace. Required by the Postman API when the PMAK's team is scoped under a Postman organization with multiple sub-teams. This is a squad id, NOT the resolver's `team-id` output: that value is a parent/org team id and is never a valid value here. On an org account whose squad list is unreadable or unusable, bootstrap fails before any workspace is created unless this input is set. | no | |
286
316
  | `spec-url` | HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path. | no | |
287
- | `spec-path` | Repo-root-relative path to the local spec file. Used for repo metadata generation and, when spec-url is not provided, as the spec source for bootstrap (read directly from the checked-out workspace). | no | |
317
+ | `spec-path` | Path to the checked-out spec file, relative to working-directory when set, otherwise the repository root. Do not repeat the working-directory prefix. Used for repo metadata and as the bootstrap spec source when spec-url is not provided. | no | |
288
318
  | `spec-files-json` | Optional content-free JSON inventory of multi-file definition members from discovery (schemaVersion 1). Empty by default. When set, inventory root must equal spec-path. Cannot be combined with spec-url. Not a directory mode — companions are listed explicitly; file content is never embedded. Forwarded to bootstrap only when spec-url is empty. | no | |
289
319
  | `preserve-oas30-type-null` | Preserve supported OpenAPI 3.0 type null oneOf members in the uploaded source while using an internal nullable view for validation and generated artifacts. | no | `false` |
290
320
  | `breaking-change-mode` | OpenAPI breaking-change comparison mode passed through to bootstrap (off, pr-native, baseline-only, or previous-spec). | no | `off` |
@@ -298,7 +328,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
298
328
  | `environment-uids-json` | JSON map of environment slug to existing Postman environment UID. When provided, repo-sync reuses these environments instead of creating new ones. | no | `{}` |
299
329
  | `governance-mapping-json` | JSON map of business domain to governance group name. | no | `{}` |
300
330
  | `env-runtime-urls-json` | JSON map of environment slug to runtime base URL. | no | `{}` |
301
- | `postman-api-key` | Postman API key (PMAK). Threaded to the wrapped actions to mint and re-mint the access token and to authenticate the Postman CLI logins (bootstrap spec lint, repo-sync generated-CI collection run). Individually optional; at least one of postman-api-key or postman-access-token is required. | no | |
331
+ | `postman-api-key` | Postman API key (PMAK). Threaded to the wrapped actions to mint and re-mint the access token and to authenticate the Postman CLI logins (the built-in smoke/contract test run, repo-sync generated-CI collection run). Individually optional; at least one of postman-api-key or postman-access-token is required. | no | |
302
332
  | `postman-access-token` | Postman access token (x-access-token). Primary credential threaded to the wrapped actions; every Postman asset operation runs through the access-token gateway. Mint it with postman-resolve-service-token-action. Individually optional; at least one of postman-api-key or postman-access-token is required. | no | |
303
333
  | `insights-postman-api-key` | Human-user Postman API key (PMAK) for Insights. Required with insights-postman-access-token only when enable-insights is true and onboarding-scope is full; do not use the service-account suite key. | no | |
304
334
  | `insights-postman-access-token` | Human-user session access token for Insights. Required with insights-postman-api-key only when enable-insights is true and onboarding-scope is full; do not use a service-token mint. | no | |
@@ -315,7 +345,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
315
345
  | `current-ref` | Explicit ref override for detached checkout push semantics. | no | |
316
346
  | `committer-name` | Commit author name for generated sync commits. | no | `Postman` |
317
347
  | `committer-email` | Commit author email for generated sync commits. | no | `support@postman.com` |
318
- | `flow-path` | Optional repo-root-relative path to the smoke flow.yaml manifest, defaulting to postman/flow.yaml inside the wrapped action. When set, the composite chains postman-cs/postman-smoke-flow-action before repo sync: a manifest at the effective path drives a curated reshape of the canonical Smoke collection, and under flow-mode auto a missing manifest is derived from spec-path and persisted to that path so repo sync commits it and the next run takes the curated path. Leave empty (default) to skip the smoke-flow step unless flow-mode requests it. | no | |
348
+ | `flow-path` | Optional path to the smoke flow.yaml manifest, relative to working-directory when set, otherwise the repository root, defaulting to postman/flow.yaml inside the wrapped action. When set, the composite chains postman-cs/postman-smoke-flow-action before repo sync: a manifest at the effective path drives a curated reshape of the canonical Smoke collection, and under flow-mode auto a missing manifest is derived from spec-path and persisted to that path so repo sync commits it and the next run takes the curated path. Leave empty (default) to skip the smoke-flow step unless flow-mode requests it. | no | |
319
349
  | `flow-mode` | Optional flow selection policy forwarded to postman-cs/postman-smoke-flow-action. Set to auto to run the smoke-flow step without a curated manifest: it derives a deterministic smoke flow from spec-path (create before read, output-to-input bindings resolved by provenance) and persists it to the effective flow path for repo sync to commit. Set to curated to require flow-path, or off to refresh the canonical Smoke collection without curation. Leave empty (default) to run the smoke-flow step only when flow-path is set, preserving the pre-flow-mode contract. | no | |
320
350
  | `flow-allow-delete` | Whether a derived smoke flow may include DELETE operations whose identifiers are proven to originate from the same run's create steps. Forwarded to postman-cs/postman-smoke-flow-action; ignored for curated manifests. Defaults to false. | no | `false` |
321
351
  | `persist-derived-flow` | Whether a freshly derived smoke flow is written to the effective flow path (flow-path or postman/flow.yaml) after a successful apply, so repo sync commits it and the next run is curated. Forwarded to postman-cs/postman-smoke-flow-action; create-only, never overwrites an existing manifest. Set false to derive without persisting. | no | `true` |
@@ -370,11 +400,11 @@ Tables are generated from `action.yml` by `npm run docs:tables`.
370
400
 
371
401
  ## How it works
372
402
 
373
- This is a composite action, the primary partner-facing entrypoint of the Postman onboarding suite. It chains up to four sibling actions in order:
403
+ This is a composite action, the primary partner-facing entrypoint of the Postman Enterprise Automation Suite. It chains up to four sibling actions in order:
374
404
 
375
405
  1. **Bootstrap** (`postman-cs/postman-bootstrap-action`) creates or reuses the workspace, uploads the spec to [Spec Hub](https://learning.postman.com/docs/design-apis/specifications/overview/), and [generates](https://learning.postman.com/docs/design-apis/specifications/generate-collections/) baseline, smoke, and contract collections.
376
- 2. **Repo sync** (`postman-cs/postman-repo-sync-action`) exports [Postman Collection v3](https://learning.postman.com/docs/use/use-collections/collections-schemas/) multi-file YAML artifacts into the repository, materializes environments, registers the mock server and smoke monitor, and optionally generates a CI workflow. Bootstrap outputs are explicitly mapped into repo-sync inputs in `action.yml`.
377
- 3. **Smoke flow** (`postman-cs/postman-smoke-flow-action`, when `flow-path` or `flow-mode` is set) reshapes the canonical Smoke collection before repo sync and the built-in test run: from the `flow.yaml` manifest at the effective flow path (`flow-path` or `postman/flow.yaml`) when one exists, otherwise derived deterministically from the spec under `flow-mode: auto` and persisted to that path. Repo sync then commits the manifest with the rest of the `postman/` tree and exports the post-reshape Smoke collection, so run 2 takes the curated path from the committed file; `derived-flow-path` reports where the manifest landed.
406
+ 2. **Smoke flow** (`postman-cs/postman-smoke-flow-action`, when `flow-path` or `flow-mode` is set) reshapes the canonical Smoke collection before repo sync and the built-in test run: from the `flow.yaml` manifest at the effective flow path (`flow-path` or `postman/flow.yaml`) when one exists, otherwise derived deterministically from the spec under `flow-mode: auto` and persisted to that path. Repo sync then commits the manifest with the rest of the `postman/` tree and exports the post-reshape Smoke collection, so run 2 takes the curated path from the committed file; `derived-flow-path` reports where the manifest landed.
407
+ 3. **Repo sync** (`postman-cs/postman-repo-sync-action`) exports [Postman Collection v3](https://learning.postman.com/docs/use/use-collections/collections-schemas/) multi-file YAML artifacts into the repository, materializes environments, registers the mock server and smoke monitor, and optionally generates a CI workflow. Bootstrap outputs are explicitly mapped into repo-sync inputs in `action.yml`.
378
408
  4. **Insights** (`postman-cs/postman-insights-onboarding-action`, only when `enable-insights: true`) links [Postman Insights](https://learning.postman.com/docs/insights/overview/) discovered services to the workspace.
379
409
 
380
410
  ```mermaid
@@ -382,9 +412,9 @@ flowchart TB
382
412
  TOKEN["resolve-service-token<br/>mints access token + team ID"] --> COMP
383
413
  AWS["aws-spec-discovery<br/>optional spec source"] -.->|"spec-url / spec-path"| COMP
384
414
  subgraph COMP["postman-api-onboarding-action (composite)"]
385
- B["bootstrap<br/>workspace + spec + collections<br/>+ injected contract tests"] --> RS["repo-sync<br/>artifacts, environments, mocks,<br/>monitors, CI workflow"]
386
- RS --> SF["smoke-flow<br/>curated flow.yaml or<br/>spec-derived (flow-mode auto)"]
387
- SF --> T["built-in smoke + contract run<br/>Postman CLI, JUnit artifact"]
415
+ B["bootstrap<br/>workspace + spec + collections<br/>+ injected contract tests"] --> SF["smoke-flow<br/>curated flow.yaml or<br/>spec-derived (flow-mode auto)"]
416
+ SF --> RS["repo-sync<br/>artifacts, environments, mocks,<br/>monitors, CI workflow"]
417
+ RS --> T["built-in smoke + contract run<br/>Postman CLI, JUnit artifact"]
388
418
  T --> INS["insights linking<br/>enable-insights: true"]
389
419
  end
390
420
  RS --> CI["generated CI workflow<br/>reruns both collections<br/>on push and schedule"]
package/action.yml CHANGED
@@ -1,5 +1,5 @@
1
- name: Postman API Onboarding
2
- description: 'Full Postman onboarding in one step: workspace bootstrap, repo sync, and optional Insights linking. Part of the Postman API Onboarding suite.'
1
+ name: 'Postman Enterprise Automation: API Onboarding'
2
+ description: 'Full Postman onboarding in one step: workspace bootstrap, repo sync, and optional Insights linking. Part of the Postman Enterprise Automation Suite.'
3
3
  author: Postman
4
4
  branding:
5
5
  icon: send
@@ -36,6 +36,10 @@ inputs:
36
36
  description: Collection lifecycle policy (refresh or version). Default refresh ensures tracked collections stay in sync with the spec.
37
37
  required: false
38
38
  default: refresh
39
+ collection-update-strategy:
40
+ description: Collection update strategy (auto or whole). Default whole preserves full collection updates.
41
+ required: false
42
+ default: whole
39
43
  spec-sync-mode:
40
44
  description: Spec lifecycle policy (update or version).
41
45
  required: false
@@ -106,7 +110,7 @@ inputs:
106
110
  description: HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path.
107
111
  required: false
108
112
  spec-path:
109
- description: Repo-root-relative path to the local spec file. Used for repo metadata generation and, when spec-url is not provided, as the spec source for bootstrap (read directly from the checked-out workspace).
113
+ description: Path to the checked-out spec file, relative to working-directory when set, otherwise the repository root. Do not repeat the working-directory prefix. Used for repo metadata and as the bootstrap spec source when spec-url is not provided.
110
114
  required: false
111
115
  spec-files-json:
112
116
  description: >-
@@ -163,7 +167,7 @@ inputs:
163
167
  required: false
164
168
  default: '{}'
165
169
  postman-api-key:
166
- description: Postman API key (PMAK). Threaded to the wrapped actions to mint and re-mint the access token and to authenticate the Postman CLI logins (bootstrap spec lint, repo-sync generated-CI collection run). Individually optional; at least one of postman-api-key or postman-access-token is required.
170
+ description: Postman API key (PMAK). Threaded to the wrapped actions to mint and re-mint the access token and to authenticate the Postman CLI logins (the built-in smoke/contract test run, repo-sync generated-CI collection run). Individually optional; at least one of postman-api-key or postman-access-token is required.
167
171
  required: false
168
172
  postman-access-token:
169
173
  description: Postman access token (x-access-token). Primary credential threaded to the wrapped actions; every Postman asset operation runs through the access-token gateway. Mint it with postman-resolve-service-token-action. Individually optional; at least one of postman-api-key or postman-access-token is required.
@@ -226,7 +230,8 @@ inputs:
226
230
  default: support@postman.com
227
231
  flow-path:
228
232
  description: |
229
- Optional repo-root-relative path to the smoke flow.yaml manifest,
233
+ Optional path to the smoke flow.yaml manifest, relative to working-directory
234
+ when set, otherwise the repository root,
230
235
  defaulting to postman/flow.yaml inside the wrapped action. When set, the
231
236
  composite chains postman-cs/postman-smoke-flow-action before repo sync:
232
237
  a manifest at the effective path drives a curated reshape of the
@@ -642,6 +647,7 @@ runs:
642
647
  POSTMAN_REGION: ${{ inputs.postman-region }}
643
648
  POSTMAN_STACK: ${{ inputs.postman-stack }}
644
649
  WORKING_DIRECTORY: ${{ inputs.working-directory }}
650
+ COLLECTION_UPDATE_STRATEGY: ${{ inputs.collection-update-strategy }}
645
651
  SPEC_PATH: ${{ inputs.spec-path }}
646
652
  CREDENTIAL_PREFLIGHT: ${{ inputs.credential-preflight }}
647
653
  REPO_WRITE_MODE: ${{ inputs.repo-write-mode }}
@@ -697,6 +703,13 @@ runs:
697
703
  exit 1
698
704
  ;;
699
705
  esac
706
+ case "$COLLECTION_UPDATE_STRATEGY" in
707
+ auto|whole) ;;
708
+ *)
709
+ echo "::error::Attempted collection-update-strategy validation failed: the provided value is unsupported. Accepted values: auto, whole. Set the collection-update-strategy input to one of those values."
710
+ exit 1
711
+ ;;
712
+ esac
700
713
  if [ "$BRANCH_TIER" != "gated" ] && [ -z "$POSTMAN_API_KEY" ] && [ -z "$POSTMAN_ACCESS_TOKEN" ]; then
701
714
  echo "::error::Attempted onboarding credential validation failed: neither postman-api-key nor postman-access-token was supplied. Provide one of those inputs and rerun."
702
715
  exit 1
@@ -735,6 +748,7 @@ runs:
735
748
  onboarding-scope: ${{ inputs.onboarding-scope }}
736
749
  sync-examples: ${{ inputs.sync-examples }}
737
750
  collection-sync-mode: ${{ inputs.collection-sync-mode }}
751
+ collection-update-strategy: ${{ inputs.collection-update-strategy }}
738
752
  spec-sync-mode: ${{ inputs.spec-sync-mode }}
739
753
  release-label: ${{ inputs.release-label }}
740
754
  domain: ${{ inputs.domain }}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postman-cs/onboarding-api",
3
- "version": "3.5.11",
3
+ "version": "3.5.13",
4
4
  "description": "Composite Postman API onboarding GitHub Action.",
5
5
  "files": [
6
6
  "action.yml",