@postman-cs/onboarding-api 3.4.6

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Postman, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,409 @@
1
+ # Postman API Onboarding
2
+
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
+
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.
6
+
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
+
9
+ ## Quick start
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.
12
+
13
+ ### Workspace-creation preflight
14
+
15
+ Before running onboarding without an existing `workspace-id`, have a Postman Admin or Super Admin verify that the system service account behind `POSTMAN_API_KEY` can create internal workspaces at the intended team or organization scope. The action cannot complete a human approval request, so the service account must be allowed to create the workspace directly.
16
+
17
+ Open the resource settings available for the target scope:
18
+
19
+ - **Standalone team:** Go to **Settings > Team settings > Team resources**, then open **Create team-wide workspaces**.
20
+ - **Postman organization:** Go to **Settings > Organization settings > Organization resources** for organization-wide workspace creation. For a workspace owned by a specific organization team, go to **Organization settings > Teams**, select the target team, and open its **Settings** tab.
21
+
22
+ Under the workspace-creation policy, either allow all members or explicitly allow the service account (or a group containing it). Also confirm that the service account is assigned to the target team. In org mode, `workspace-team-id` selects the team that owns a new workspace; it does not grant workspace-creation permission. See [Manage organization and team resources](https://learning.postman.com/docs/administration/managing-your-team/manage-team-workspaces/) and [Manage service account identities](https://learning.postman.com/docs/administration/service-accounts/).
23
+
24
+ When `workspace-id` points to an existing workspace, create permission is not required, but the service account must have sufficient access to update that workspace and its resources.
25
+
26
+ ```yaml
27
+ name: Postman API onboarding
28
+
29
+ on:
30
+ workflow_dispatch:
31
+
32
+ jobs:
33
+ onboarding:
34
+ runs-on: ubuntu-latest
35
+ permissions:
36
+ actions: write
37
+ contents: write
38
+ steps:
39
+ - uses: actions/checkout@v5
40
+
41
+ - id: postman-token
42
+ uses: postman-cs/postman-resolve-service-token-action@v2
43
+ with:
44
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
45
+ postman-region: us
46
+
47
+ - id: onboard
48
+ uses: postman-cs/postman-api-onboarding-action@v3
49
+ with:
50
+ project-name: core-payments
51
+ spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
52
+ postman-region: us
53
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
54
+ postman-access-token: ${{ steps.postman-token.outputs.token }}
55
+ postman-team-id: ${{ steps.postman-token.outputs.team-id }}
56
+ github-token: ${{ github.token }}
57
+ ```
58
+
59
+ That run creates or reuses a [Postman workspace](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/overview/), uploads the spec, generates baseline, smoke, and contract collections, materializes [environments](https://learning.postman.com/docs/use/send-requests/variables/managing-environments/), registers a [mock server](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/) and [monitor](https://learning.postman.com/docs/monitoring-your-api/intro-monitors/), commits exported artifacts to the repository, and runs the smoke and contract collections with JUnit output.
60
+
61
+ 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
+
63
+ ## Which action should I use?
64
+
65
+ | Scenario | Start with | Why |
66
+ | --- | --- | --- |
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. |
68
+ | 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
+ | 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
+ | 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. |
71
+ | Apply a curated Smoke flow | [Postman Onboarding: Smoke Flow](https://github.com/postman-cs/postman-smoke-flow-action) | Standalone flow update for the canonical Smoke collection. |
72
+ | Sync generated artifacts without the composite wrapper | [Postman Onboarding: Repo Sync](https://github.com/postman-cs/postman-repo-sync-action) | Lower-level artifact, environment, mock, monitor, and CI workflow sync. |
73
+ | Link an existing workspace to Insights | [Postman Onboarding: Insights Linking](https://github.com/postman-cs/postman-insights-onboarding-action) | Lower-level Insights service-to-workspace binding. |
74
+
75
+ ## Scenario guide
76
+
77
+ - [Quick start](#quick-start): new GitHub API repository with service-token credential resolution.
78
+ - [Governance and environments](#governance-and-environments): workspace ownership, governance groups, environments, and runtime URLs.
79
+ - [Existing service refresh](#existing-service-refresh): reuse known Postman asset IDs while updating the spec and generated artifacts.
80
+ - [Protected branches](#protected-branch-repos-commit-only-plus-pr): create a sync commit for a pull request instead of pushing directly.
81
+ - [Insights linking](#insights-linking): connect discovered services to the onboarded workspace.
82
+ - [AWS spec discovery](#aws-spec-discovery): discover the spec first, then feed the result into this composite action.
83
+ - [Deferred tests](#deferred-tests): skip the built-in Postman CLI run when the caller workflow must enrich auth first.
84
+ - [Support](SUPPORT.md), [security](SECURITY.md), and [release policy](RELEASE_POLICY.md): marketplace support, vulnerability reporting, and version guidance.
85
+
86
+ ## Credentials and region
87
+
88
+ 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).
89
+
90
+ ### Authentication matrix
91
+
92
+ | Credential or permission | Where it appears | Required for | Source and permissions | Expiration behavior |
93
+ | --- | --- | --- | --- | --- |
94
+ | 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 |
95
+ | 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` |
96
+ | 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 |
97
+ | 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 |
98
+ | GitHub token | `github-token`, `gh-fallback-token`, or `${{ github.token }}` | Artifact commits, repository variables, generated workflow files, and optional secret writes | `GITHUB_TOKEN` needs `contents: write`; generated workflow updates need `actions: write`; repository secret writes need a PAT or GitHub App token with secrets write permission | `GITHUB_TOKEN` is job-scoped; PAT/App token lifetime follows its issuer policy |
99
+ | AWS OIDC | `permissions: id-token: write` plus `aws-actions/configure-aws-credentials` | AWS Spec Discovery before onboarding | GitHub OIDC role assumption with least-privilege read permissions for API Gateway, AppSync, EventBridge, Lambda, or the providers you enable | Temporary AWS credentials for the job; no static AWS key is stored |
100
+
101
+ Keep service-token, onboarding, and downstream actions on the same `postman-region`. Use `credential-preflight: enforce` when a workflow supplies both a PMAK and access token and must fail before creating assets if they resolve to different parent orgs.
102
+
103
+ ## Examples
104
+
105
+ The examples below include credential resolution when they need `postman-access-token` or `postman-team-id`.
106
+
107
+ ### Governance and environments
108
+
109
+ ```yaml
110
+ - uses: actions/checkout@v5
111
+ - id: postman-token
112
+ uses: postman-cs/postman-resolve-service-token-action@v2
113
+ with:
114
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
115
+ postman-region: us
116
+
117
+ - uses: postman-cs/postman-api-onboarding-action@v3
118
+ with:
119
+ project-name: core-payments
120
+ domain: core-banking
121
+ domain-code: AF
122
+ spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
123
+ postman-region: us
124
+ environments-json: '["prod","stage"]'
125
+ governance-mapping-json: '{"core-banking":"Core Banking"}'
126
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
127
+ postman-access-token: ${{ steps.postman-token.outputs.token }}
128
+ postman-team-id: ${{ steps.postman-token.outputs.team-id }}
129
+ github-token: ${{ secrets.GITHUB_TOKEN }}
130
+ gh-fallback-token: ${{ secrets.GH_FALLBACK_TOKEN }}
131
+ ```
132
+
133
+ ### Existing service refresh
134
+
135
+ Target an existing workspace/spec/collection set and suppress generated CI workflow output for repos that already have their own pipeline layout. `spec-url` (or `spec-path`) is still required because the bootstrap step updates the Spec Hub asset from source on every run.
136
+
137
+ ```yaml
138
+ - uses: actions/checkout@v5
139
+ - id: postman-token
140
+ uses: postman-cs/postman-resolve-service-token-action@v2
141
+ with:
142
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
143
+ postman-region: us
144
+
145
+ - uses: postman-cs/postman-api-onboarding-action@v3
146
+ with:
147
+ project-name: core-payments
148
+ workspace-id: ws-123
149
+ spec-id: spec-123
150
+ baseline-collection-id: col-baseline
151
+ smoke-collection-id: col-smoke
152
+ contract-collection-id: col-contract
153
+ spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
154
+ postman-region: us
155
+ generate-ci-workflow: false
156
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
157
+ postman-access-token: ${{ steps.postman-token.outputs.token }}
158
+ postman-team-id: ${{ steps.postman-token.outputs.team-id }}
159
+ ```
160
+
161
+ ### Protected-branch repos: commit-only plus PR
162
+
163
+ For repositories whose branch protection requires all changes to land through pull requests, run the action with `repo-write-mode: commit-only` on a temporary sync branch, then push the branch and open a PR when `commit-sha` is non-empty. Postman provisioning succeeds independently of merge approval, and the phase outcome outputs (`bootstrap-outcome`, `repo-sync-outcome`, `insights-outcome`) tell you which half needs attention on partial failure.
164
+
165
+ ```yaml
166
+ - id: onboard
167
+ uses: postman-cs/postman-api-onboarding-action@v3
168
+ with:
169
+ project-name: core-payments
170
+ spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
171
+ postman-region: us
172
+ repo-write-mode: commit-only
173
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
174
+ github-token: ${{ secrets.GITHUB_TOKEN }}
175
+ ```
176
+
177
+ The full pattern, including sync-branch creation and programmatic PR opening, is in [docs/protected-branch-workflows.md](docs/protected-branch-workflows.md).
178
+
179
+ ### Insights linking
180
+
181
+ When `enable-insights: true` and `onboarding-scope: full`, the action chains `postman-cs/postman-insights-onboarding-action@v2.4.4` after bootstrap and repo sync, using the workspace from bootstrap plus the first environment from `environments-json`. Spec-only onboarding skips Insights because that path intentionally does not create the required environment. This release accepts live human sessions identified by `user_type=human` even when `consumerType` is absent. Insights still requires a separate human-user PMAK and human-user session access token; do not pass the service-account credentials used by bootstrap and repo sync.
182
+
183
+ ```yaml
184
+ - uses: actions/checkout@v5
185
+ - id: postman-token
186
+ uses: postman-cs/postman-resolve-service-token-action@v2
187
+ with:
188
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
189
+ postman-region: us
190
+
191
+ - uses: postman-cs/postman-api-onboarding-action@v3
192
+ with:
193
+ project-name: core-payments
194
+ spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
195
+ postman-region: us
196
+ enable-insights: true
197
+ cluster-name: my-cluster
198
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
199
+ postman-access-token: ${{ steps.postman-token.outputs.token }}
200
+ insights-postman-api-key: ${{ secrets.POSTMAN_INSIGHTS_USER_API_KEY }}
201
+ insights-postman-access-token: ${{ secrets.POSTMAN_INSIGHTS_USER_ACCESS_TOKEN }}
202
+ postman-team-id: ${{ steps.postman-token.outputs.team-id }}
203
+ ```
204
+
205
+ ### AWS spec discovery
206
+
207
+ Run AWS spec discovery before this composite action when the OpenAPI document should come from API Gateway or another AWS source. Feed the exported spec path into `spec-path`.
208
+
209
+ ```yaml
210
+ - uses: actions/checkout@v5
211
+ - id: postman-token
212
+ uses: postman-cs/postman-resolve-service-token-action@v2
213
+ with:
214
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
215
+ postman-region: us
216
+
217
+ - id: discover-spec
218
+ uses: postman-cs/postman-aws-spec-discovery-action@v2
219
+ with:
220
+ aws-region: us-east-1
221
+ - uses: postman-cs/postman-api-onboarding-action@v3
222
+ with:
223
+ project-name: core-payments
224
+ spec-path: ${{ steps.discover-spec.outputs.spec-path }}
225
+ postman-region: us
226
+ postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
227
+ postman-access-token: ${{ steps.postman-token.outputs.token }}
228
+ postman-team-id: ${{ steps.postman-token.outputs.team-id }}
229
+ ```
230
+
231
+ ### Deferred tests
232
+
233
+ Set `skip-built-in-tests: 'true'` when the caller workflow must perform post-onboarding setup (bearer-token minting, mTLS bootstrap, vault-hydrated secrets, dynamic env enrichment) before the smoke and contract suites can authenticate, then run the collections itself using the `collections-json` and `environment-uids-json` outputs. The full caller pattern is in [docs/deferred-tests.md](docs/deferred-tests.md).
234
+
235
+ ### Private mocks
236
+
237
+ Default mock servers are public and anonymous. Teams that prohibit public mocks set `mock-visibility: private`. Repo-sync then installs a secret-free request hook on the smoke and contract collections, emits `mock-auth-required: true`, and never persists a credential.
238
+
239
+ Where the transient `postmanPrivateMockApiKey` variable comes from:
240
+
241
+ - **Generated CI** — supplied automatically from the `POSTMAN_API_KEY` secret this suite already provisions for `postman login`. No extra secret and no workflow edit.
242
+ - **Manual runs in the Postman app** — enable `mock-environment-enabled: true`. The `<project> - Mock` environment carries `postmanPrivateMockApiKey` as an empty secret-typed variable; paste a key with access to the mock.
243
+ - **A runner you wire yourself** — read the `mock-auth-required` output and pass the variable however that system handles secrets.
244
+
245
+ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays inert on runs that target a real environment. A private-mock request with no key logs a console warning naming the variable.
246
+
247
+ ## Inputs
248
+
249
+ <!-- inputs-table:start -->
250
+ | Name | Description | Required | Default |
251
+ | --- | --- | --- | --- |
252
+ | `workspace-id` | Existing Postman workspace ID. | no | |
253
+ | `spec-id` | Existing Postman spec ID. | no | |
254
+ | `baseline-collection-id` | Existing baseline collection ID. | no | |
255
+ | `smoke-collection-id` | Existing smoke collection ID. | no | |
256
+ | `contract-collection-id` | Existing contract collection ID. | no | |
257
+ | `onboarding-scope` | Onboarding scope. Use full for the complete pipeline or spec-only for workspace/spec onboarding without generated assets. | no | `full` |
258
+ | `sync-examples` | Whether linked spec/collection relations should enable example syncing. | no | `true` |
259
+ | `collection-sync-mode` | Collection lifecycle policy (refresh or version). Default refresh ensures tracked collections stay in sync with the spec. | no | `refresh` |
260
+ | `spec-sync-mode` | Spec lifecycle policy (update or version). | no | `update` |
261
+ | `release-label` | Optional release label for versioned specs and collections. When omitted during versioned sync, derived from GitHub tag or branch metadata. | no | |
262
+ | `monitor-id` | Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one. | no | |
263
+ | `mock-url` | Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one. | no | |
264
+ | `mock-visibility` | Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync. | no | `public` |
265
+ | `mock-environment-enabled` | Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential. | no | `false` |
266
+ | `monitor-cron` | Cron expression for monitor scheduling (e.g. '0 */6 * * *'). When empty, the monitor is created disabled and triggered to run once per workflow invocation (and once on every subsequent run). | no | |
267
+ | `generate-ci-workflow` | Whether to generate the CI workflow file. | no | `true` |
268
+ | `ci-workflow-path` | Path to write the generated CI workflow file. | no | `.github/workflows/ci.yml` |
269
+ | `ci-runner-os` | Runner operating system for the generated CI workflow. Use windows for native PowerShell Azure DevOps CI. | no | `linux` |
270
+ | `project-name` | Service project name used across bootstrap and repo sync phases. | yes | |
271
+ | `repo-url` | Explicit repository URL forwarded to bootstrap and repo sync. Overrides CI auto-detection when a caller needs an isolated synthetic repository identity. | no | |
272
+ | `domain` | Business domain used for governance assignment. | no | |
273
+ | `domain-code` | Short domain code used in workspace naming. | no | |
274
+ | `governance-group` | Postman governance workspace group name. Overrides the postman-governance-group repository custom property and domain mapping. | no | |
275
+ | `requester-email` | Requester email used for workspace membership. | no | |
276
+ | `workspace-admin-user-ids` | Comma-separated workspace admin user ids. | no | |
277
+ | `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 | |
278
+ | `spec-url` | HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path. | no | |
279
+ | `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 | |
280
+ | `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 | |
281
+ | `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` |
282
+ | `breaking-change-mode` | OpenAPI breaking-change comparison mode passed through to bootstrap (off, pr-native, baseline-only, or previous-spec). | no | `off` |
283
+ | `breaking-baseline-spec-path` | Repo-root-relative baseline OpenAPI spec path used by bootstrap baseline-only mode and pr-native fallback. | no | |
284
+ | `breaking-rules-path` | Repo-root-relative openapi-changes rules file passed through to bootstrap. Missing files are ignored. | no | `changes-rules.yaml` |
285
+ | `breaking-target-ref` | Optional target branch or git ref override for bootstrap pr-native breaking-change comparisons. | no | |
286
+ | `breaking-summary-path` | Optional markdown breaking-change report path. Defaults to a bootstrap runner-temp file. | no | |
287
+ | `breaking-log-path` | Optional raw breaking-change log path. Defaults to a bootstrap runner-temp file. | no | |
288
+ | `environments-json` | JSON array of environment slugs to materialize. | no | `["prod"]` |
289
+ | `system-env-map-json` | JSON map of environment slug to system environment id. | no | `{}` |
290
+ | `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 | `{}` |
291
+ | `governance-mapping-json` | JSON map of business domain to governance group name. | no | `{}` |
292
+ | `env-runtime-urls-json` | JSON map of environment slug to runtime base URL. | no | `{}` |
293
+ | `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 | |
294
+ | `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 | |
295
+ | `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 | |
296
+ | `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 | |
297
+ | `credential-preflight` | Credential identity preflight policy forwarded to bootstrap and repo sync. 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` |
298
+ | `branch-strategy` | Branch-aware sync strategy. v2 preserves legacy by default; the future v3 major will default to publish-gate after its release gates close. | no | `legacy` |
299
+ | `canonical-branch` | Explicit canonical branch. Defaults to the GitHub event repository default branch for non-legacy strategies. | no | |
300
+ | `channels` | Comma-separated channel map, for example develop=DEV, staging=STAGE, release/*=RC. | no | |
301
+ | `preview-ttl` | Sliding preview retention TTL in days, forwarded to repo-sync. | no | `30` |
302
+ | `postman-team-id` | Explicit Postman team ID override for org-mode integration calls. | no | |
303
+ | `postman-region` | Postman data residency region for public API and Postman CLI calls. One of us or eu. | no | `us` |
304
+ | `github-token` | GitHub token used for repo variables and generated commits. | no | |
305
+ | `gh-fallback-token` | Fallback GitHub token for variable and workflow-file APIs. | no | |
306
+ | `repo-write-mode` | Repo mutation mode for generated assets and workflow files. One of none, commit-only, or commit-and-push. | no | `commit-and-push` |
307
+ | `current-ref` | Explicit ref override for detached checkout push semantics. | no | |
308
+ | `committer-name` | Commit author name for generated sync commits. | no | `Postman` |
309
+ | `committer-email` | Commit author email for generated sync commits. | no | `support@postman.com` |
310
+ | `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 | |
311
+ | `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 | |
312
+ | `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` |
313
+ | `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` |
314
+ | `enable-insights` | Whether to enable Postman Insights. | no | `false` |
315
+ | `skip-built-in-tests` | When 'true', skip the built-in smoke and contract Postman CLI test run and JUnit artifact upload that normally happen inside this action. Set this to 'true' when the caller workflow needs to perform additional post-onboarding setup (e.g. bearer-token injection, mTLS bootstrap, vault-hydrated secrets, dynamic env enrichment) before the smoke and contract suites can authenticate successfully, and will run the tests itself afterward. Default 'false' preserves existing behavior for all current callers. | no | `false` |
316
+ | `cluster-name` | Insights cluster name passed to the downstream Insights onboarding step. | no | |
317
+ | `org-mode` | Whether the Postman team uses org-mode. When true, x-entity-team-id is included on integration calls. Non-org teams must omit this header. | no | `false` |
318
+ | `ssl-client-cert` | Base64-encoded PEM client certificate for mTLS. Passed through to repo-sync for CI workflow generation. | no | |
319
+ | `ssl-client-key` | Base64-encoded PEM client private key. Passed through to repo-sync. | no | |
320
+ | `ssl-client-passphrase` | Passphrase for encrypted private key. Passed through to repo-sync. | no | |
321
+ | `ssl-extra-ca-certs` | Base64-encoded PEM additional CA certificates. Passed through to repo-sync. | no | |
322
+ <!-- inputs-table:end -->
323
+
324
+ Tables are generated from `action.yml` by `npm run docs:tables`.
325
+
326
+ ## Outputs
327
+
328
+ <!-- outputs-table:start -->
329
+ | Name | Description |
330
+ | --- | --- |
331
+ | `workspace-id` | Postman workspace ID. |
332
+ | `workspace-url` | Postman workspace URL. |
333
+ | `spec-id` | Uploaded Postman spec ID. |
334
+ | `collections-json` | JSON summary of generated collections. |
335
+ | `breaking-change-status` | OpenAPI breaking-change check status from bootstrap. |
336
+ | `breaking-change-summary-json` | JSON summary of the OpenAPI breaking-change check from bootstrap. |
337
+ | `environment-uids-json` | JSON map of environment slug to Postman environment uid. |
338
+ | `mock-url` | Mock server URL. |
339
+ | `mock-visibility` | Authoritatively observed mock visibility: public or private. |
340
+ | `mock-auth-required` | Whether the collection runner must supply postmanPrivateMockApiKey at runtime. |
341
+ | `mock-environment-uid` | Dedicated manual-validation environment UID when mock-environment-enabled succeeds. |
342
+ | `mock-environment-status` | Whether the optional manual-validation mock environment succeeded, was skipped, or failed. |
343
+ | `monitor-id` | Smoke monitor ID. |
344
+ | `repo-sync-summary-json` | JSON summary of repo materialization and workspace sync planning. |
345
+ | `commit-sha` | Commit SHA produced by repo-write-mode. |
346
+ | `sync-status` | Branch-aware sync status, including skipped-branch-gate for credential-free gated runs. |
347
+ | `spec-version-url` | Read-only URL for the canonical Spec Hub version finalized by repo-sync. |
348
+ | `flow-apply-status` | Smoke-flow apply result status (empty when the smoke-flow step did not run). |
349
+ | `flow-apply-summary-json` | JSON summary of smoke-flow application results and warnings (empty when the smoke-flow step did not run). |
350
+ | `derived-flow-path` | Repo-relative path where the smoke-flow step persisted a derived flow.yaml this run (empty for curated manifests, persistence opt-out, uncurated refreshes, and skipped runs). The reordered repo-sync step commits the file with the rest of the postman tree. |
351
+ | `bootstrap-outcome` | GitHub Actions runner outcome for the bootstrap step. |
352
+ | `repo-sync-outcome` | GitHub Actions runner outcome for the repo sync step. |
353
+ | `smoke-flow-outcome` | GitHub Actions runner outcome for the smoke-flow step (skipped when neither flow-path nor flow-mode is set). |
354
+ | `insights-outcome` | GitHub Actions runner outcome for the Insights onboarding step. |
355
+ | `insights-status` | Insights onboarding status (success, not-found, error, or empty if insights disabled). |
356
+ | `insights-verification-token` | Team verification token for Insights DaemonSet configuration. |
357
+ | `insights-application-id` | Insights application binding ID. |
358
+ | `insights-discovered-service-id` | Discovered service ID from Insights agent. |
359
+ | `insights-discovered-service-name` | Discovered service name from Insights agent. |
360
+ | `insights-collection-id` | Insights API Catalog collection ID. |
361
+ <!-- outputs-table:end -->
362
+
363
+ ## How it works
364
+
365
+ This is a composite action, the primary partner-facing entrypoint of the Postman onboarding suite. It chains up to four sibling actions in order:
366
+
367
+ 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.
368
+ 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`.
369
+ 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.
370
+ 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.
371
+
372
+ ```mermaid
373
+ flowchart TB
374
+ TOKEN["resolve-service-token<br/>mints access token + team ID"] --> COMP
375
+ AWS["aws-spec-discovery<br/>optional spec source"] -.->|"spec-url / spec-path"| COMP
376
+ subgraph COMP["postman-api-onboarding-action (composite)"]
377
+ B["bootstrap<br/>workspace + spec + collections<br/>+ injected contract tests"] --> RS["repo-sync<br/>artifacts, environments, mocks,<br/>monitors, CI workflow"]
378
+ RS --> SF["smoke-flow<br/>curated flow.yaml or<br/>spec-derived (flow-mode auto)"]
379
+ SF --> T["built-in smoke + contract run<br/>Postman CLI, JUnit artifact"]
380
+ T --> INS["insights linking<br/>enable-insights: true"]
381
+ end
382
+ RS --> CI["generated CI workflow<br/>reruns both collections<br/>on push and schedule"]
383
+ ```
384
+
385
+ `resolve-service-token` and `aws-spec-discovery` are standalone steps that feed the composite's inputs; they are not invoked from inside it. `smoke-flow` runs inside the composite when `flow-path` or `flow-mode` is set, and remains usable standalone against the composite's outputs.
386
+
387
+ Between repo sync and Insights, the action runs the generated smoke and contract collections with the [Postman CLI](https://learning.postman.com/docs/postman-cli/postman-cli-collections/) and uploads [JUnit results](https://learning.postman.com/docs/postman-cli/postman-cli-reporters/) as a workflow artifact (skippable via `skip-built-in-tests`). Inputs are backend-neutral and kebab-case. Full contract details, output mapping, and phase outcome semantics are in [docs/contract.md](docs/contract.md).
388
+
389
+ Running outside GitHub Actions (GitLab CI, Bitbucket Pipelines, Azure DevOps)? The bootstrap and repo-sync CLIs cover that: see [docs/non-github-ci.md](docs/non-github-ci.md).
390
+
391
+ Releases use immutable `v3.x.y` tags with `v3` as the rolling release channel; pin an immutable tag for reproducibility. See [RELEASE_POLICY.md](RELEASE_POLICY.md).
392
+
393
+ ## Resources
394
+
395
+ - npm package: [@postman-cs/onboarding-api](https://www.npmjs.com/package/@postman-cs/onboarding-api)
396
+ - Docs in this repo: [credentials](docs/credentials.md), [contract and output mapping](docs/contract.md), [protected-branch workflows](docs/protected-branch-workflows.md), [deferred tests](docs/deferred-tests.md), [non-GitHub CI](docs/non-github-ci.md)
397
+ - Marketplace docs: [support](SUPPORT.md), [security](SECURITY.md), [release policy](RELEASE_POLICY.md)
398
+ - 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/)
399
+ - Postman workspace 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/), [collections](https://learning.postman.com/docs/use/use-collections/overview/), [environments](https://learning.postman.com/docs/use/send-requests/variables/managing-environments/), [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/)
400
+ - Postman CI and governance references: [Postman CLI collection runs](https://learning.postman.com/docs/postman-cli/postman-cli-collections/), [CLI reporters](https://learning.postman.com/docs/postman-cli/postman-cli-reporters/), [API governance rules](https://learning.postman.com/docs/api-governance/configurable-rules/configuring-api-governance-rules/), [Postman Insights](https://learning.postman.com/docs/insights/overview/)
401
+
402
+
403
+ ## Telemetry
404
+
405
+ This composite action emits no telemetry of its own; each wired child action sends one anonymous usage event per run (action name/version, outcome, coarse CI metadata; never secrets, spec content, or repo names). Set `POSTMAN_ACTIONS_TELEMETRY=off` or `DO_NOT_TRACK=1` at the workflow or job level to disable it for every child step, or point `POSTMAN_ACTIONS_TELEMETRY_ENDPOINT` at your own collector the same way.
406
+
407
+ ## License
408
+
409
+ [MIT](LICENSE)