postman-cs/Postman Onboarding: Workspace Bootstrap
Provision a Postman workspace from an OpenAPI spec with generated collections. Part of the Postman API Onboarding suite.
View on GitHubTrust Signals
- Scorecard Score
- Scorecard 4–6scored Jun 12, 2026
- Maintenance Recency
- Activelast commit Jul 10, 2026
- License
- MIT
Pinned Snippet
uses: postman-cs/postman-bootstrap-action@6dfc5f3e3a1e0839a694564cd44fab17a25d6dee # v2.9.0tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| workspace-id | Existing Postman workspace ID | no | — |
| spec-id | Existing Postman spec ID | no | — |
| baseline-collection-id | Existing baseline collection ID | no | — |
| smoke-collection-id | Existing smoke collection ID | no | — |
| contract-collection-id | Existing contract collection ID | no | — |
| additional-collections-dir | Workspace-relative directory containing curated Postman v2.1 JSON/YAML files or canonical HTTP collection v3 Local View directories to create or update. | no | — |
| sync-examples | Whether linked spec/collection relations should enable example syncing | no | true |
| collection-sync-mode | Collection lifecycle policy (refresh or version) | no | refresh |
| spec-sync-mode | Spec lifecycle policy (update or version) | no | update |
| release-label | Optional release label used for versioned specs and collections | no | — |
| project-name | Service project name | yes | — |
| domain | Business domain for the service | no | — |
| domain-code | Workspace naming prefix | no | — |
| governance-group | Postman governance workspace group name. Overrides the postman-governance-group repository custom property and domain mapping. | no | — |
| requester-email | Requester email for audit context | no | — |
| workspace-admin-user-ids | Comma-separated workspace admin user ids | no | — |
| workspace-team-id | Numeric sub-team ID for org-mode workspace creation. Required when your Postman team is an org with multiple sub-teams. Run the action without this input to see available sub-teams listed in the error output. | no | — |
| spec-url | HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path. | no | — |
| spec-path | Local filesystem path to the OpenAPI document (relative to the workspace). Provide either spec-url or spec-path. | no | — |
| 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. | no | "" |
| protocol | API spec protocol. auto (default) detects from content/extension. openapi flows through Spec Hub; graphql (SDL/introspection), grpc (.proto), and soap (WSDL) build and instrument a Postman collection directly. | no | auto |
| protocol-endpoint-url | Endpoint URL/authority used by generated non-OpenAPI requests (e.g. {{baseUrl}}/graphql, grpc://host:port). Supports Postman variable interpolation. Ignored for openapi. | no | "" |
| openapi-version | OpenAPI specification version override (3.0 or 3.1). When not set, the version is auto-detected from the spec content. | no | "" |
| preserve-oas30-type-null | Opt-in compatibility mode for OpenAPI 3.0 oneOf schemas that pair one normal schema with a null-only member. The action uploads the original source bytes unchanged and uses an internal nullable true view for validation and generated artifacts. All unrelated validation and lint errors remain enforced. | no | false |
| breaking-change-mode | OpenAPI breaking-change comparison mode (off, pr-native, baseline-only, or previous-spec) | no | off |
| breaking-baseline-spec-path | Workspace-relative baseline OpenAPI spec path used by baseline-only mode and pr-native fallback | no | — |
| breaking-rules-path | Workspace-relative openapi-changes rules file. Missing files are ignored. | no | changes-rules.yaml |
| breaking-target-ref | Optional target branch or git ref override for pr-native breaking-change comparisons | no | — |
| breaking-summary-path | Optional markdown report output path. Defaults to a runner-temp file. | no | "" |
| breaking-log-path | Optional raw command log output path. Defaults to a runner-temp file. | no | "" |
| governance-mapping-json | Legacy JSON map of business domain to governance group name. Prefer governance-group or the postman-governance-group repository custom property. | no | {} |
| github-token | GitHub token used to read the postman-governance-group repository custom property | no | — |
| gh-fallback-token | Fallback GitHub token used to read repository custom properties when github-token cannot | no | — |
| postman-api-key | Postman service-account API key used only to preflight the mint credential with GET /me and mint or re-mint the short-lived postman-access-token. It is never used for asset or Postman CLI operations. Optional when postman-access-token is supplied. | no | — |
| postman-access-token | Postman service-account access token (x-access-token). Every identity and asset operation runs through the access-token gateway. Optional when postman-api-key is supplied for token minting. CLI/binary usage may instead set POSTMAN_ACCESS_TOKEN. | no | — |
| credential-preflight | Access-token session preflight policy. warn (default) continues with reactive diagnostics when session identity is unavailable; enforce fails before any workspace is created. | no | warn |
| branch-strategy | Branch-aware sync strategy. legacy (default) keeps branch-blind behavior; publish-gate restricts canonical writes to the canonical branch and runs credential-free static validation on other branches; preview additionally maintains suffixed per-branch preview asset sets. | no | legacy |
| canonical-branch | Explicit canonical branch (the sole writer of canonical assets). Defaults to the provider-resolved default branch; required on providers without a default-branch variable (Bitbucket, Azure DevOps) when branch-strategy is not legacy. | no | — |
| channels | Comma-separated channel map for long-lived promotion branches, e.g. "develop=DEV, staging=STAGE, release/*=RC". Channel branches maintain prefix-named parallel asset sets and never mutate canonical assets. | no | — |
| integration-backend | Advanced/internal. Integration backend for managed workspace connectivity; leave unset to use the default. | no | — |
| folder-strategy | Folder organization strategy for generated collections (Paths or Tags) | no | Paths |
| nested-folder-hierarchy | When folder-strategy is Tags, enables nested folder hierarchy | no | false |
| request-name-source | Determines how requests are named in generated collections (Fallback or URL) | no | Fallback |
| postman-region | Postman data residency region for access-token minting and gateway calls. | no | us |
| postman-stack | Postman stack profile. Leave at the default unless Postman support directs otherwise. | no | prod |
Outputs
| name | description |
|---|---|
| workspace-id | Postman workspace ID |
| workspace-url | Postman workspace URL |
| workspace-name | Postman workspace name |
| spec-id | Uploaded Postman spec ID |
| baseline-collection-id | Baseline collection ID |
| smoke-collection-id | Smoke collection ID |
| contract-collection-id | Contract collection ID |
| collections-json | JSON summary of generated collections |
| lint-summary-json | JSON summary of validation findings. Bootstrap does not invoke an API-key-authenticated Postman CLI lint. |
| breaking-change-status | OpenAPI breaking-change check status |
| breaking-change-summary-json | JSON summary of the OpenAPI breaking-change check |
| sync-status | Branch-aware sync status: synced, skipped-branch-gate, or empty under branch-strategy legacy. |
| branch-decision | Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION). |
| spec-version-tag | Native Spec Hub version tag applied on this canonical publish (tag-per-publish), empty when tagging was skipped (no-op sync, non-canonical run, or legacy client). |
| spec-version-url | Reserved for the repo-sync finalizer; bootstrap does not tag before complete onboarding. |
| spec-content-changed | Whether bootstrap changed canonical spec content; repo-sync uses this to skip native version tags on no-op syncs. |