name: 'Postman Onboarding: Workspace Bootstrap'
description: Provision a Postman workspace from an OpenAPI spec with generated collections. Part of the Postman API Onboarding suite.
author: Postman
branding:
  icon: box
  color: orange
inputs:

  workspace-id:
    description: Existing Postman workspace ID
    required: false
  spec-id:
    description: Existing Postman spec ID
    required: false
  baseline-collection-id:
    description: Existing baseline collection ID
    required: false
  smoke-collection-id:
    description: Existing smoke collection ID
    required: false
  contract-collection-id:
    description: Existing contract collection ID
    required: false
  additional-collections-dir:
    description: Workspace-relative directory containing curated Postman v2.1 JSON/YAML files or canonical HTTP collection v3 Local View directories to create or update.
    required: false
  onboarding-scope:
    description: Onboarding scope. Use full for the complete pipeline or spec-only for OpenAPI workspace and specification onboarding without generated assets.
    required: false
    default: full
  sync-examples:
    description: Whether linked spec/collection relations should enable example syncing
    required: false
    default: 'true'
  collection-sync-mode:
    description: Collection lifecycle policy (refresh or version)
    required: false
    default: refresh
  spec-sync-mode:
    description: Spec lifecycle policy (update or version)
    required: false
    default: update
  release-label:
    description: Optional release label used for versioned specs and collections
    required: false
  project-name:
    description: Service project name
    required: true
  domain:
    description: Business domain for the service
    required: false
  domain-code:
    description: Workspace naming prefix
    required: false
  governance-group:
    description: Postman governance workspace group name. Overrides the postman-governance-group repository custom property and domain mapping.
    required: false
  requester-email:
    description: Requester email for audit context
    required: false
  workspace-admin-user-ids:
    description: Comma-separated workspace admin user ids
    required: false
  workspace-team-id:
    description: >-
      Numeric SUB-TEAM (squad) id that should own the created org-mode
      workspace. Required when your Postman team is an org with multiple
      sub-teams. This is a squad id, NOT the parent/org team id from the
      resolver's `team-id` output; that value is never valid here. On an org
      account whose squad list is unreadable or unusable, bootstrap now fails
      before any workspace is created unless this input is set. Run once on a
      healthy account without it to see available sub-teams listed in the error
      output.
    required: false
  spec-url:
    description: HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path.
    required: false
  spec-path:
    description: Local filesystem path to the OpenAPI document (relative to the workspace). Provide either spec-url or spec-path.
    required: false
  spec-files-json:
    description: >-
      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.
    required: false
    default: ''
  protocol:
    description: API spec protocol. auto (default) detects from content/extension. openapi uploads the canonical spec to Spec Hub and builds baseline/smoke/contract collections locally (import/deep-update); graphql (SDL/introspection), grpc (.proto), and soap (WSDL) build and instrument a Postman collection directly.
    required: false
    default: auto
  protocol-endpoint-url:
    description: Endpoint URL/authority used by generated non-OpenAPI requests (e.g. {{baseUrl}}/graphql, grpc://host:port). Supports Postman variable interpolation. Ignored for openapi.
    required: false
    default: ''
  openapi-version:
    description: OpenAPI specification version override (3.0 or 3.1). When not set, the version is auto-detected from the spec content.
    required: false
    default: ''
  preserve-oas30-type-null:
    description: '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.'
    required: false
    default: 'false'
  breaking-change-mode:
    description: OpenAPI breaking-change comparison mode (off, pr-native, baseline-only, or previous-spec)
    required: false
    default: 'off'
  breaking-baseline-spec-path:
    description: Workspace-relative baseline OpenAPI spec path used by baseline-only mode and pr-native fallback
    required: false
  breaking-rules-path:
    description: Workspace-relative openapi-changes rules file. Missing files are ignored.
    required: false
    default: changes-rules.yaml
  breaking-target-ref:
    description: Optional target branch or git ref override for pr-native breaking-change comparisons
    required: false
  breaking-summary-path:
    description: Optional markdown report output path. Defaults to a runner-temp file.
    required: false
    default: ''
  breaking-log-path:
    description: Optional raw command log output path. Defaults to a runner-temp file.
    required: false
    default: ''
  governance-mapping-json:
    description: Legacy JSON map of business domain to governance group name. Prefer governance-group or the postman-governance-group repository custom property.
    required: false
    default: '{}'
  github-token:
    description: GitHub token used to read the postman-governance-group repository custom property
    required: false
  gh-fallback-token:
    description: Fallback GitHub token used to read repository custom properties when github-token cannot
    required: false
  postman-api-key:
    description: 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.
    required: false
  postman-access-token:
    description: 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.
    required: false
  credential-preflight:
    description: "Access-token session preflight policy. warn (default) continues with reactive diagnostics when session identity is unavailable; enforce fails before any workspace is created."
    required: false
    default: warn
  branch-strategy:
    description: "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."
    required: false
    default: legacy
  canonical-branch:
    description: 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.
    required: false
  channels:
    description: '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.'
    required: false
  integration-backend:
    description: Advanced/internal. Integration backend for managed workspace connectivity; leave unset to use the default.
    required: false
  folder-strategy:
    description: Folder organization strategy for generated collections (Paths or Tags)
    required: false
    default: Paths
  nested-folder-hierarchy:
    description: When folder-strategy is Tags, enables nested folder hierarchy
    required: false
    default: 'false'
  request-name-source:
    description: Determines how requests are named in generated collections (Fallback or URL)
    required: false
    default: Fallback
  secrets-resolver:
    description: >-
      Cloud secret store backing the optional "00 - Resolve Secrets" helper request placed at
      the start of generated Smoke and Contract collections. One of none, aws, azure, or gcp.
      Defaults to none, which injects no helper request. The helper is a local-run convenience
      only; it is skipped when CI=true.
    required: false
    default: none
  postman-region:
    description: Postman data residency region for access-token minting and gateway calls.
    required: false
    default: us
  postman-stack:
    description: 'Postman stack profile. Leave at the default unless Postman support directs otherwise.'
    required: false
    default: prod
outputs:
  workspace-id:
    description: Postman workspace ID
  workspace-url:
    description: Postman workspace URL
  workspace-name:
    description: Postman workspace name
  spec-id:
    description: Uploaded Postman spec ID
  baseline-collection-id:
    description: Baseline collection ID
  smoke-collection-id:
    description: Smoke collection ID
  contract-collection-id:
    description: Contract collection ID
  collections-json:
    description: JSON summary of generated collections
  prebuilt-collections-json:
    description: Digest-bound JSON manifest of locally materialized Collection v3 trees (schemaVersion 1) for repo-sync reuse
  openapi-operation-ledger-json:
    description: Sanitized local OpenAPI orchestration operation ledger (schemaVersion 1) with counts and timings
  lint-summary-json:
    description: JSON summary of validation findings. Bootstrap does not invoke an API-key-authenticated Postman CLI lint.
  breaking-change-status:
    description: OpenAPI breaking-change check status
  breaking-change-summary-json:
    description: JSON summary of the OpenAPI breaking-change check
  sync-status:
    description: "Branch-aware sync status: synced, skipped-branch-gate, or empty under branch-strategy legacy."
  branch-decision:
    description: Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION).
  spec-version-tag:
    description: 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:
    description: Reserved for the repo-sync finalizer; bootstrap does not tag before complete onboarding.
  spec-content-changed:
    description: Whether bootstrap changed canonical spec content; repo-sync uses this to skip native version tags on no-op syncs.
runs:
  using: node24
  main: dist/action.cjs