postman-cs/Postman Onboarding: Repo Sync
Export Postman collections and environments into your repo with CI wiring. 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-repo-sync-action@e87eccc2e9cc1de6e1b914a634c37b631c9a35ca # v2.1.0tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| generate-ci-workflow | Whether to generate the CI workflow file | no | true |
| ci-workflow-path | Path to write the generated CI workflow file. Defaults to azure-pipelines.yml for Azure DevOps, .github/workflows/ci.yml otherwise. | no | — |
| 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 for environment, mock, and monitor naming. | yes | — |
| workspace-id | Postman workspace ID used for workspace-link and export metadata. | no | — |
| baseline-collection-id | Baseline collection ID used for exported artifacts and mock server creation. | no | — |
| monitor-type | Type of monitor to create ("cloud" or "cli"). "cli" will skip cloud monitor creation and rely on the CI workflow. | no | cloud |
| smoke-collection-id | Smoke collection ID used for monitor creation. | no | — |
| contract-collection-id | Contract collection ID used for exported artifacts. | no | — |
| collection-sync-mode | Collection sync lifecycle mode (refresh or version). | no | refresh |
| spec-sync-mode | Spec sync lifecycle mode (update or version). | no | update |
| release-label | Optional release label used for versioned naming. | 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 | "" |
| environments-json | JSON array of environment slugs to create or update. | no | ["prod"] |
| git-provider | Git provider override ('github', 'gitlab', 'bitbucket', 'azure-devops'). Auto-detected from environment when omitted. | no | — |
| ado-token | Azure DevOps personal access token or system token used to push commits in Azure Pipelines. Defaults to SYSTEM_ACCESSTOKEN when available. | no | — |
| repo-url | Explicit repository URL (GitHub, GitLab, or Azure DevOps). Defaults to the URL inferred from runner environment when omitted. | no | — |
| integration-backend | Advanced/internal. Integration backend for managed workspace linking and environment sync; leave unset to use the default. | no | — |
| workspace-link-enabled | Enable workspace linking. | no | true |
| environment-sync-enabled | Enable association of Postman environments to system environments. | no | true |
| system-env-map-json | JSON map of environment slug to system environment id. | no | {} |
| environment-uids-json | JSON map of environment slug to Postman environment uid. | no | {} |
| env-runtime-urls-json | JSON map of environment slug to runtime base URL. | no | {} |
| artifact-dir | Root directory for exported Postman artifacts. | no | postman |
| repo-write-mode | Repo mutation mode for generated artifacts and workflow files. | no | commit-and-push |
| current-ref | Explicit ref override for push-changes when the checkout is detached. | no | — |
| committer-name | Git committer name for sync commits. | no | Postman |
| committer-email | Git committer email for sync commits. | no | support@postman.com |
| postman-api-key | Postman API key (PMAK). Used only to mint/re-mint the access token (via postman-resolve-service-token-action) and for the Postman CLI spec-lint login. Asset operations (environments, collections, mocks, monitors) run on the access-token gateway and do not use the PMAK. Optional when a valid postman-access-token is supplied; required only for the CLI lint path. | no | — |
| postman-access-token | Postman access token minted by postman-resolve-service-token-action. Required for all asset operations (environment create/get/update, collection read, mock, monitor) which run through the access-token gateway. Also used for workspace linking, system environment association, and generated API-key creation. When omitted, the action mints one from postman-api-key (service-account PMAK); if that mint also fails the action fails fast — PMAK is never an asset-routing fallback. | no | — |
| team-id | Postman team ID resolved by postman-resolve-service-token-action. Primary team scope for all downstream actions; included as x-entity-team-id in org-mode Bifrost calls. Falls back to POSTMAN_TEAM_ID when omitted. Set explicitly for org-mode teams. | no | "" |
| credential-preflight | Credential identity preflight policy. 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. Both modes warn when postman-access-token is not a service-account token. | no | warn |
| branch-strategy | Branch-aware sync strategy. legacy (default) keeps branch-blind behavior; publish-gate restricts canonical writes to the canonical branch and skips repo-sync 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 and tracked state). 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 | — |
| preview-ttl | Sliding TTL in days for preview asset sets (refreshed on every successful preview sync; the retention contract of last resort when no provider credential is available for branch-existence checks). | no | 30 |
| github-token | GitHub token used for repo variable persistence and commits. | no | — |
| gh-fallback-token | Fallback token for repository variable APIs and workflow-file pushes. | no | — |
| org-mode | Whether the Postman team uses org-mode. When true, x-entity-team-id is included in Postman integration API calls. Non-org teams must omit this header. | no | false |
| ci-workflow-base64 | Optional base64-encoded ci.yml content. Defaults to the built-in template. | no | — |
| ssl-client-cert | Base64-encoded PEM client certificate for Postman CLI mTLS runs. | no | — |
| ssl-client-key | Base64-encoded PEM client private key for Postman CLI mTLS runs. | no | — |
| ssl-client-passphrase | Optional passphrase for encrypted ssl-client-key. | no | — |
| ssl-extra-ca-certs | Optional base64-encoded PEM CA certificate bundle for custom trust. | no | — |
| spec-id | Spec Hub UID emitted by bootstrap's spec-id output. When set, it is persisted into .postman/resources.yaml cloudResources so later runs and the generated CI workflow can resolve the spec without re-discovery. | no | — |
| spec-content-changed | Whether bootstrap changed canonical spec content. Native Spec Hub tag publication is skipped on no-op syncs. | no | true |
| spec-path | Optional repo-root-relative path to the local OpenAPI file. Recorded in .postman/resources.yaml and .postman/workflows.yaml metadata so the committed artifacts point back at the spec source in this repository; the file itself is not uploaded by this action. | 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. Leave at the default unless Postman support directs otherwise. | no | prod |
Outputs
| name | description |
|---|---|
| integration-backend | Resolved integration backend for the onboarding run. |
| resolved-current-ref | Resolved push target based on current-ref semantics. |
| workspace-link-status | Whether workspace linking succeeded, was skipped, or failed. |
| environment-sync-status | Whether environment sync succeeded, was skipped, or failed. |
| environment-uids-json | JSON map of environment slug to Postman environment uid. |
| mock-url | Created or reused mock server URL. |
| monitor-id | Created or reused smoke monitor ID. |
| repo-sync-summary-json | JSON summary of repo materialization and workspace sync outputs. |
| commit-sha | Commit SHA produced by repo-write-mode, if any. |
| 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 created after successful canonical repo-sync finalization. |
| spec-version-url | Read-only URL for the tagged Spec Hub snapshot. |