postman-cs/Postman API Onboarding
Full Postman onboarding in one step: workspace bootstrap, repo sync, and optional Insights linking. 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-api-onboarding-action@1d98cabaae6c0ff26ea3983cd4d4a0cc0a2b0833 # v2.0.1tags 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 | — |
| sync-examples | Whether linked spec/collection relations should enable example syncing. | no | true |
| collection-sync-mode | Collection lifecycle policy (refresh or version). Default refresh ensures tracked collections stay in sync with the spec. | no | refresh |
| spec-sync-mode | Spec lifecycle policy (update or version). | no | update |
| release-label | Optional release label for versioned specs and collections. When omitted during versioned sync, derived from GitHub tag or branch metadata. | no | — |
| monitor-id | Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one. | no | — |
| mock-url | Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one. | no | — |
| 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 | "" |
| generate-ci-workflow | Whether to generate the CI workflow file. | no | true |
| ci-workflow-path | Path to write the generated CI workflow file. | no | .github/workflows/ci.yml |
| ci-runner-os | Runner operating system for the generated CI workflow. Use windows for native PowerShell Azure DevOps CI. | no | linux |
| project-name | Service project name used across bootstrap and repo sync phases. | yes | — |
| domain | Business domain used for governance assignment. | no | — |
| domain-code | Short domain code used in workspace naming. | no | — |
| governance-group | Postman governance workspace group name. Overrides the postman-governance-group repository custom property and domain mapping. | no | — |
| requester-email | Requester email used for workspace membership. | 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 by the Postman API when the PMAK's team is scoped under an organization. | no | — |
| spec-url | HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path. | no | — |
| 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 | — |
| 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 | "" |
| breaking-change-mode | OpenAPI breaking-change comparison mode passed through to bootstrap (off, pr-native, baseline-only, or previous-spec). | no | off |
| breaking-baseline-spec-path | Repo-root-relative baseline OpenAPI spec path used by bootstrap baseline-only mode and pr-native fallback. | no | — |
| breaking-rules-path | Repo-root-relative openapi-changes rules file passed through to bootstrap. Missing files are ignored. | no | changes-rules.yaml |
| breaking-target-ref | Optional target branch or git ref override for bootstrap pr-native breaking-change comparisons. | no | — |
| breaking-summary-path | Optional markdown breaking-change report path. Defaults to a bootstrap runner-temp file. | no | "" |
| breaking-log-path | Optional raw breaking-change log path. Defaults to a bootstrap runner-temp file. | no | "" |
| environments-json | JSON array of environment slugs to materialize. | no | ["prod"] |
| system-env-map-json | JSON map of environment slug to system environment id. | no | {} |
| 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 | {} |
| governance-mapping-json | JSON map of business domain to governance group name. | no | {} |
| env-runtime-urls-json | JSON map of environment slug to runtime base URL. | no | {} |
| 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 | — |
| 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 | — |
| insights-postman-api-key | Human-user Postman API key (PMAK) for Insights. Required with insights-postman-access-token only when enable-insights is true; do not use the service-account suite key. | no | — |
| insights-postman-access-token | Human-user session access token for Insights. Required with insights-postman-api-key only when enable-insights is true; do not use a service-token mint. | no | — |
| 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 |
| 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 |
| canonical-branch | Explicit canonical branch. Defaults to the GitHub event repository default branch for non-legacy strategies. | no | — |
| channels | Comma-separated channel map, for example develop=DEV, staging=STAGE, release/*=RC. | no | — |
| preview-ttl | Sliding preview retention TTL in days, forwarded to repo-sync. | no | 30 |
| postman-team-id | Explicit Postman team ID override for org-mode integration calls. | no | — |
| postman-region | Postman data residency region for public API and Postman CLI calls. One of us or eu. | no | us |
| postman-stack | Postman stack profile. Use prod for Marketplace workflows; EU data residency requires prod. | no | prod |
| github-token | GitHub token used for repo variables and generated commits. | no | — |
| gh-fallback-token | Fallback GitHub token for variable and workflow-file APIs. | no | — |
| 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 |
| current-ref | Explicit ref override for detached checkout push semantics. | no | — |
| committer-name | Commit author name for generated sync commits. | no | Postman |
| committer-email | Commit author email for generated sync commits. | no | support@postman.com |
| enable-insights | Whether to enable Postman Insights. | no | false |
| 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 |
| cluster-name | Insights cluster name passed to the downstream Insights onboarding step. | no | — |
| integration-backend | Advanced/internal. Integration backend used to coordinate onboarding phases; leave unset to use the default. | no | — |
| 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 |
| ssl-client-cert | Base64-encoded PEM client certificate for mTLS. Passed through to repo-sync for CI workflow generation. | no | — |
| ssl-client-key | Base64-encoded PEM client private key. Passed through to repo-sync. | no | — |
| ssl-client-passphrase | Passphrase for encrypted private key. Passed through to repo-sync. | no | — |
| ssl-extra-ca-certs | Base64-encoded PEM additional CA certificates. Passed through to repo-sync. | no | — |
Outputs
| name | description |
|---|---|
| integration-backend | Resolved integration backend for the onboarding run. |
| workspace-id | Postman workspace ID. |
| workspace-url | Postman workspace URL. |
| spec-id | Uploaded Postman spec ID. |
| collections-json | JSON summary of generated collections. |
| breaking-change-status | OpenAPI breaking-change check status from bootstrap. |
| breaking-change-summary-json | JSON summary of the OpenAPI breaking-change check from bootstrap. |
| environment-uids-json | JSON map of environment slug to Postman environment uid. |
| mock-url | Mock server URL. |
| monitor-id | Smoke monitor ID. |
| repo-sync-summary-json | JSON summary of repo materialization and workspace sync planning. |
| commit-sha | Commit SHA produced by repo-write-mode. |
| sync-status | Branch-aware sync status, including skipped-branch-gate for credential-free gated runs. |
| spec-version-url | Read-only URL for the canonical Spec Hub version finalized by repo-sync. |
| bootstrap-outcome | GitHub Actions runner outcome for the bootstrap step. |
| repo-sync-outcome | GitHub Actions runner outcome for the repo sync step. |
| insights-outcome | GitHub Actions runner outcome for the Insights onboarding step. |
| insights-status | Insights onboarding status (success, not-found, error, or empty if insights disabled). |
| insights-verification-token | Team verification token for Insights DaemonSet configuration. |
| insights-application-id | Insights application binding ID. |
| insights-discovered-service-id | Discovered service ID from Insights agent. |
| insights-discovered-service-name | Discovered service name from Insights agent. |
| insights-collection-id | Insights API Catalog collection ID. |