@postman-cs/onboarding-api 3.5.10 → 3.5.12

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 +40 -11
  2. package/action.yml +7 -6
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -8,7 +8,13 @@ Canonical entrypoint for the Postman API Onboarding suite. Use this composite ac
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,6 +66,12 @@ 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 |
@@ -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 |
@@ -284,7 +313,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
284
313
  | `workspace-admin-user-ids` | Comma-separated workspace admin user ids. | no | |
285
314
  | `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
315
  | `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 | |
316
+ | `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
317
  | `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
318
  | `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
319
  | `breaking-change-mode` | OpenAPI breaking-change comparison mode passed through to bootstrap (off, pr-native, baseline-only, or previous-spec). | no | `off` |
@@ -298,7 +327,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
298
327
  | `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
328
  | `governance-mapping-json` | JSON map of business domain to governance group name. | no | `{}` |
300
329
  | `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 | |
330
+ | `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
331
  | `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
332
  | `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
333
  | `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 +344,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
315
344
  | `current-ref` | Explicit ref override for detached checkout push semantics. | no | |
316
345
  | `committer-name` | Commit author name for generated sync commits. | no | `Postman` |
317
346
  | `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 | |
347
+ | `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
348
  | `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
349
  | `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
350
  | `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` |
@@ -373,8 +402,8 @@ Tables are generated from `action.yml` by `npm run docs:tables`.
373
402
  This is a composite action, the primary partner-facing entrypoint of the Postman onboarding suite. It chains up to four sibling actions in order:
374
403
 
375
404
  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.
405
+ 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.
406
+ 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
407
  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
408
 
380
409
  ```mermaid
@@ -382,9 +411,9 @@ flowchart TB
382
411
  TOKEN["resolve-service-token<br/>mints access token + team ID"] --> COMP
383
412
  AWS["aws-spec-discovery<br/>optional spec source"] -.->|"spec-url / spec-path"| COMP
384
413
  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"]
414
+ B["bootstrap<br/>workspace + spec + collections<br/>+ injected contract tests"] --> SF["smoke-flow<br/>curated flow.yaml or<br/>spec-derived (flow-mode auto)"]
415
+ SF --> RS["repo-sync<br/>artifacts, environments, mocks,<br/>monitors, CI workflow"]
416
+ RS --> T["built-in smoke + contract run<br/>Postman CLI, JUnit artifact"]
388
417
  T --> INS["insights linking<br/>enable-insights: true"]
389
418
  end
390
419
  RS --> CI["generated CI workflow<br/>reruns both collections<br/>on push and schedule"]
package/action.yml CHANGED
@@ -106,7 +106,7 @@ inputs:
106
106
  description: HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path.
107
107
  required: false
108
108
  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).
109
+ 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
110
  required: false
111
111
  spec-files-json:
112
112
  description: >-
@@ -163,7 +163,7 @@ inputs:
163
163
  required: false
164
164
  default: '{}'
165
165
  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.
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 (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
167
  required: false
168
168
  postman-access-token:
169
169
  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 +226,8 @@ inputs:
226
226
  default: support@postman.com
227
227
  flow-path:
228
228
  description: |
229
- Optional repo-root-relative path to the smoke flow.yaml manifest,
229
+ Optional path to the smoke flow.yaml manifest, relative to working-directory
230
+ when set, otherwise the repository root,
230
231
  defaulting to postman/flow.yaml inside the wrapped action. When set, the
231
232
  composite chains postman-cs/postman-smoke-flow-action before repo sync:
232
233
  a manifest at the effective path drives a curated reshape of the
@@ -715,7 +716,7 @@ runs:
715
716
  - id: bootstrap
716
717
  name: Bootstrap Postman Assets
717
718
  if: ${{ steps.branch_decision.outputs.tier != 'gated' }}
718
- uses: postman-cs/postman-bootstrap-action@v2.21.10
719
+ uses: postman-cs/postman-bootstrap-action@v2.22.0
719
720
  env:
720
721
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
721
722
  POSTMAN_BRANCH_DECISION: ${{ steps.branch_decision.outputs.branch-decision }}
@@ -774,7 +775,7 @@ runs:
774
775
  - id: smoke_flow
775
776
  name: Apply Smoke flow
776
777
  if: ${{ inputs.onboarding-scope == 'full' && (inputs.flow-path != '' || inputs.flow-mode != '') && steps.branch_decision.outputs.tier != 'gated' }}
777
- uses: postman-cs/postman-smoke-flow-action@v3.7.4
778
+ uses: postman-cs/postman-smoke-flow-action@v3.7.5
778
779
  env:
779
780
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
780
781
  POSTMAN_BRANCH_DECISION: ${{ steps.branch_decision.outputs.branch-decision }}
@@ -799,7 +800,7 @@ runs:
799
800
  - id: repo_sync
800
801
  name: Sync Repository and Workspace
801
802
  if: ${{ steps.branch_decision.outputs.tier != 'gated' }}
802
- uses: postman-cs/postman-repo-sync-action@v2.10.9
803
+ uses: postman-cs/postman-repo-sync-action@v2.11.1
803
804
  env:
804
805
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
805
806
  POSTMAN_BRANCH_DECISION: ${{ steps.branch_decision.outputs.branch-decision }}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postman-cs/onboarding-api",
3
- "version": "3.5.10",
3
+ "version": "3.5.12",
4
4
  "description": "Composite Postman API onboarding GitHub Action.",
5
5
  "files": [
6
6
  "action.yml",