Postman API Onboarding

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.

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, Smoke generated tests, and Contract Enforcement Layers.

Quick start

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, 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.

Workspace-creation preflight

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.

Open the resource settings available for the target scope:

• Standalone team: Go to Settings > Team settings > Team resources, then open Create team-wide workspaces.
• 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.

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 and Manage service account identities.

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.

name: Postman API onboarding

on:
  workflow_dispatch:

jobs:
  onboarding:
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
    steps:
      - uses: actions/checkout@v5

      - id: postman-token
        uses: postman-cs/postman-resolve-service-token-action@v2
        with:
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-region: us

      - id: onboard
        uses: postman-cs/postman-api-onboarding-action@v3
        with:
          project-name: core-payments
          spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman-token.outputs.token }}
          postman-team-id: ${{ steps.postman-token.outputs.team-id }}
          github-token: ${{ github.token }}

That run creates or reuses a Postman workspace, uploads the spec, generates baseline, smoke, and contract collections, materializes environments, registers a mock server and monitor, commits exported artifacts to the repository, and runs the smoke and contract collections with JUnit output.

Use postman-region: eu for EU data residency. Keep the same region on the service-token step and the composite action.

Which action should I use?

| Scenario | Start with | Why | | --- | --- | --- | | Full GitHub onboarding from an OpenAPI spec | Postman API Onboarding | Canonical suite entrypoint. Chains bootstrap, repo sync, tests, and optional Insights. | | Mint an access token and resolve team ID | Postman Onboarding: Service Token | Primary credential path for this composite action. Run it before onboarding. | | Discover an OpenAPI spec from AWS | Postman Onboarding: AWS Spec Discovery | Produces a spec URL or artifact that can feed this composite action. | | Provision only the Postman workspace and collections | Postman Onboarding: Workspace Bootstrap | Lower-level action for custom pipelines that do not want repo sync. | | Apply a curated Smoke flow | Postman Onboarding: Smoke Flow | Standalone flow update for the canonical Smoke collection. | | Sync generated artifacts without the composite wrapper | Postman Onboarding: Repo Sync | Lower-level artifact, environment, mock, monitor, and CI workflow sync. | | Link an existing workspace to Insights | Postman Onboarding: Insights Linking | Lower-level Insights service-to-workspace binding. |

Scenario guide

• Quick start: new GitHub API repository with service-token credential resolution.
• Governance and environments: workspace ownership, governance groups, environments, and runtime URLs.
• Existing service refresh: reuse known Postman asset IDs while updating the spec and generated artifacts.
• Protected branches: create a sync commit for a pull request instead of pushing directly.
• Insights linking: connect discovered services to the onboarded workspace.
• AWS spec discovery: discover the spec first, then feed the result into this composite action.
• Deferred tests: skip the built-in Postman CLI run when the caller workflow must enrich auth first.
• Support, security, and release policy: marketplace support, vulnerability reporting, and version guidance.

Credentials and region

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.

Authentication matrix

| Credential or permission | Where it appears | Required for | Source and permissions | Expiration behavior | | --- | --- | --- | --- | --- | | 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 API key | Long-lived until rotated in Postman and updated in CI | | 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 | | 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 | | 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 | | 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 | | 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 |

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.

Examples

The examples below include credential resolution when they need postman-access-token or postman-team-id.

Governance and environments

- uses: actions/checkout@v5
- id: postman-token
  uses: postman-cs/postman-resolve-service-token-action@v2
  with:
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-region: us

- uses: postman-cs/postman-api-onboarding-action@v3
  with:
    project-name: core-payments
    domain: core-banking
    domain-code: AF
    spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
    postman-region: us
    environments-json: '["prod","stage"]'
    governance-mapping-json: '{"core-banking":"Core Banking"}'
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-access-token: ${{ steps.postman-token.outputs.token }}
    postman-team-id: ${{ steps.postman-token.outputs.team-id }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    gh-fallback-token: ${{ secrets.GH_FALLBACK_TOKEN }}

Existing service refresh

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.

- uses: actions/checkout@v5
- id: postman-token
  uses: postman-cs/postman-resolve-service-token-action@v2
  with:
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-region: us

- uses: postman-cs/postman-api-onboarding-action@v3
  with:
    project-name: core-payments
    workspace-id: ws-123
    spec-id: spec-123
    baseline-collection-id: col-baseline
    smoke-collection-id: col-smoke
    contract-collection-id: col-contract
    spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
    postman-region: us
    generate-ci-workflow: false
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-access-token: ${{ steps.postman-token.outputs.token }}
    postman-team-id: ${{ steps.postman-token.outputs.team-id }}

Protected-branch repos: commit-only plus PR

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.

- id: onboard
  uses: postman-cs/postman-api-onboarding-action@v3
  with:
    project-name: core-payments
    spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
    postman-region: us
    repo-write-mode: commit-only
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    github-token: ${{ secrets.GITHUB_TOKEN }}

The full pattern, including sync-branch creation and programmatic PR opening, is in docs/protected-branch-workflows.md.

Insights linking

When enable-insights: true and onboarding-scope: full, the action chains postman-cs/[email protected] 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.

- uses: actions/checkout@v5
- id: postman-token
  uses: postman-cs/postman-resolve-service-token-action@v2
  with:
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-region: us

- uses: postman-cs/postman-api-onboarding-action@v3
  with:
    project-name: core-payments
    spec-url: https://raw.githubusercontent.com/postman-cs/postman-api-onboarding-action/main/examples/core-payments-openapi.yaml
    postman-region: us
    enable-insights: true
    cluster-name: my-cluster
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-access-token: ${{ steps.postman-token.outputs.token }}
    insights-postman-api-key: ${{ secrets.POSTMAN_INSIGHTS_USER_API_KEY }}
    insights-postman-access-token: ${{ secrets.POSTMAN_INSIGHTS_USER_ACCESS_TOKEN }}
    postman-team-id: ${{ steps.postman-token.outputs.team-id }}

AWS spec discovery

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.

- uses: actions/checkout@v5
- id: postman-token
  uses: postman-cs/postman-resolve-service-token-action@v2
  with:
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-region: us

- id: discover-spec
  uses: postman-cs/postman-aws-spec-discovery-action@v2
  with:
    aws-region: us-east-1
- uses: postman-cs/postman-api-onboarding-action@v3
  with:
    project-name: core-payments
    spec-path: ${{ steps.discover-spec.outputs.spec-path }}
    postman-region: us
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-access-token: ${{ steps.postman-token.outputs.token }}
    postman-team-id: ${{ steps.postman-token.outputs.team-id }}

Deferred tests

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.

Private mocks

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.

Where the transient postmanPrivateMockApiKey variable comes from:

• Generated CI — supplied automatically from the POSTMAN_API_KEY secret this suite already provisions for postman login. No extra secret and no workflow edit.
• 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.
• A runner you wire yourself — read the mock-auth-required output and pass the variable however that system handles secrets.

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.

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 | | | onboarding-scope | Onboarding scope. Use full for the complete pipeline or spec-only for workspace/spec onboarding without generated assets. | no | full | | 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 | | | 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 | | 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 | | 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 | | | 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 | | | 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 (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 | | | 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 | | | 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 | | 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 and onboarding-scope is full; 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 and onboarding-scope is full; 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 | | 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 | [email protected] | | 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 | | | 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 | | | 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 | | 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 | | 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 | | | 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 | |

Tables are generated from action.yml by npm run docs:tables.

Outputs

| Name | Description | | --- | --- | | 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. | | mock-visibility | Authoritatively observed mock visibility: public or private. | | mock-auth-required | Whether the collection runner must supply postmanPrivateMockApiKey at runtime. | | mock-environment-uid | Dedicated manual-validation environment UID when mock-environment-enabled succeeds. | | mock-environment-status | Whether the optional manual-validation mock environment succeeded, was skipped, or failed. | | 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. | | flow-apply-status | Smoke-flow apply result status (empty when the smoke-flow step did not run). | | flow-apply-summary-json | JSON summary of smoke-flow application results and warnings (empty when the smoke-flow step did not run). | | 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. | | bootstrap-outcome | GitHub Actions runner outcome for the bootstrap step. | | repo-sync-outcome | GitHub Actions runner outcome for the repo sync step. | | smoke-flow-outcome | GitHub Actions runner outcome for the smoke-flow step (skipped when neither flow-path nor flow-mode is set). | | 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. |

How it works

This is a composite action, the primary partner-facing entrypoint of the Postman onboarding suite. It chains up to four sibling actions in order:

1. Bootstrap (postman-cs/postman-bootstrap-action) creates or reuses the workspace, uploads the spec to Spec Hub, and generates baseline, smoke, and contract collections.
2. Repo sync (postman-cs/postman-repo-sync-action) exports Postman Collection v3 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.
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.
4. Insights (postman-cs/postman-insights-onboarding-action, only when enable-insights: true) links Postman Insights discovered services to the workspace.

flowchart TB
    TOKEN["resolve-service-token<br/>mints access token + team ID"] --> COMP
    AWS["aws-spec-discovery<br/>optional spec source"] -.->|"spec-url / spec-path"| COMP
    subgraph COMP["postman-api-onboarding-action (composite)"]
        B["bootstrap<br/>workspace + spec + collections<br/>+ injected contract tests"] --> RS["repo-sync<br/>artifacts, environments, mocks,<br/>monitors, CI workflow"]
        RS --> SF["smoke-flow<br/>curated flow.yaml or<br/>spec-derived (flow-mode auto)"]
        SF --> T["built-in smoke + contract run<br/>Postman CLI, JUnit artifact"]
        T --> INS["insights linking<br/>enable-insights: true"]
    end
    RS --> CI["generated CI workflow<br/>reruns both collections<br/>on push and schedule"]

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.

Between repo sync and Insights, the action runs the generated smoke and contract collections with the Postman CLI and uploads JUnit results 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.

Running outside GitHub Actions (GitLab CI, Bitbucket Pipelines, Azure DevOps)? The bootstrap and repo-sync CLIs cover that: see docs/non-github-ci.md.

Releases use immutable v3.x.y tags with v3 as the rolling release channel; pin an immutable tag for reproducibility. See RELEASE_POLICY.md.

Resources

• npm package: @postman-cse/onboarding-api
• Docs in this repo: credentials, contract and output mapping, protected-branch workflows, deferred tests, non-GitHub CI
• Marketplace docs: support, security, release policy
• Postman API and auth references: Postman API, API authentication, service accounts, EU data residency
• Postman workspace resources: workspaces, Spec Hub, import a specification, generate collections, collections, environments, mock servers, monitors
• Postman CI and governance references: Postman CLI collection runs, CLI reporters, API governance rules, Postman Insights

Telemetry

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.

License

MIT