Postman Enterprise Automation: Repo Sync

Exports Postman collections and environments into your repository and wires CI, mock servers, and monitors around them.

Part of the Postman Enterprise Automation Suite; the composite action's README has the full action-picker table.

• Usage
• Examples
• Monorepos
• Inputs / Outputs
• How it works

Usage

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

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

      - uses: postman-cs/postman-repo-sync-action@v2
        with:
          project-name: core-payments
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman-auth.outputs.token }}
          team-id: ${{ steps.postman-auth.outputs.team-id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

actions/checkout must run before this action. project-name is the only schema-required input. A useful sync also needs a Postman API key or a service-token step that can mint one, plus workspace and collection IDs from inputs or .postman/resources.yaml.

The example permissions let GITHUB_TOKEN commit generated artifacts and update the generated workflow file. contents: write is required for repo-write-mode: commit-only and commit-and-push. actions: write is required when generate-ci-workflow writes under .github/workflows/. Repository secret persistence, such as a generated POSTMAN_API_KEY or mTLS certificate secret, needs gh-fallback-token with permission to manage Actions secrets.

postman-region controls the Postman public API host and generated Postman CLI login region. Use us for https://api.getpostman.com and eu for https://api.eu.postman.com when the team uses EU data residency.

Examples

Full sync with workspace assets

- uses: postman-cs/postman-repo-sync-action@v2
  with:
    project-name: core-payments
    workspace-id: ws-123
    baseline-collection-id: col-baseline
    smoke-collection-id: col-smoke
    contract-collection-id: col-contract
    postman-region: us
    environments-json: '["prod","stage"]'
    env-runtime-urls-json: '{"prod":"https://api.example.com","stage":"https://stage-api.example.com"}'
    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
    postman-access-token: ${{ steps.postman-auth.outputs.token }}
    team-id: ${{ steps.postman-auth.outputs.team-id }}
    github-token: ${{ secrets.GITHUB_TOKEN }}

postman-access-token is required: every asset operation (environment create/get/update, collection read, mock, monitor) plus workspace-to-repository linking and system environment association runs through the access-token gateway. Use postman-resolve-service-token-action to mint it at runtime from a Postman service account PMAK. Without it the action fails fast — the PMAK is not an asset-routing fallback; it only mints/re-mints the access token, powers the generated CI workflow's postman login --with-api-key, and mints the CI POSTMAN_API_KEY secret. See docs/credentials.md.

To manage the complete values for an environment, use a rich entry in the same input. String entries remain backward-compatible and receive generated values; rich entries replace the environment values exactly as supplied (plus the action's branch-ownership marker when applicable).

environments-json: >-
  [{"slug":"dev","values":[{"key":"baseUrl","value":"https://dev.example.com"},{"key":"jwtToken","value":"","type":"secret"}]}]

Secret-typed values must be empty. Supply the real secret as a masked runtime variable from the customer's vault when running the collection; repo-sync neither reads nor persists that value. value, type, and enabled default to "", "default", and true. env-runtime-urls-json and generated credential slots apply only to string entries because a rich entry is the complete desired definition.

Disable CI workflow generation

For existing repositories that already own their CI workflow, disable workflow generation:

with:
  generate-ci-workflow: false

Custom CI workflow path

Write the generated workflow somewhere other than .github/workflows/ci.yml:

with:
  ci-workflow-path: .github/workflows/postman-sync.yml

Commit-only mode for protected branches

If branch protection requires pull requests, run on a temporary branch with commit-only writes, then create the PR in a later workflow step. Use this for customer-managed PR workflows.

with:
  repo-write-mode: commit-only

repo-write-mode options:

| Mode | Behavior | | --- | --- | | commit-and-push | Commit generated files and push them back to the current checked out ref. | | commit-only | Commit generated files without pushing. | | none | Write files in the workspace only. |

Reuse an existing mock server and monitor

Pass mock-url or monitor-id to validate and reuse existing mock servers or monitors instead of creating new ones:

with:
  mock-url: https://abc123.mock.pstmn.io
  monitor-id: 1e2f3a4b-monitor-id

Repo-sync defaults to private mocks so anonymous requests cannot expose response examples. Set mock-visibility: public only when anonymous validation is intentional. Explicit, discovered, and newly created mocks must match the requested visibility and the expected baseline collection/environment; unknown visibility, stale URLs, and identity mismatches fail before mock-url is emitted.

For private mocks, repo-sync emits mock-auth-required: true and installs a secret-free collection-root request hook in the exported smoke and contract collections. The hook reads the transient postmanPrivateMockApiKey variable and sends it as x-api-key, and only to *.mock.pstmn.io hosts, so it stays inert on runs that target a real environment. Repo-sync never writes that credential to a collection, environment, output, or repository artifact.

Where that variable comes from depends on who is running the collection:

• Generated CI supplies it automatically from the POSTMAN_API_KEY secret repo-sync already provisions for postman login. No extra secret and no workflow edit.
• Manual runs in the Postman app use the <project> - Mock environment, which carries postmanPrivateMockApiKey as an empty secret-typed variable. Paste a key with access to the mock. Requires mock-environment-enabled: true.
• A runner you wire yourself reads mock-auth-required and passes the variable however that system handles secrets.

A request to a private mock with no key set logs a console warning naming the variable, so a 401 explains its own fix.

For manual collection validation against the resolved mock, opt in to a dedicated Postman environment:

with:
  mock-environment-enabled: true

On canonical and legacy runs, the action creates or reuses <project> - Mock, sets its baseUrl to the validated mock URL, and emits mock-environment-uid. Preview and channel runs skip it so branch retention cleanup cannot leak an untracked environment. Its exported representation lives at postman/mocks/manual-validation.postman_environment.json; it is deliberately excluded from environment-uids-json, system-environment associations, monitors, and generated CI environment selection. Select it explicitly when running baseline, Smoke, or Contract collections manually. Repo-sync never replaces the runtime prod or dev baseUrl with a mock URL.

Monorepos

Set working-directory to a service directory to keep its postman/ and .postman/ state isolated. Use one repository-root dispatcher workflow; nested .github/workflows/ directories are ignored by GitHub. See the monorepo onboarding guide for the supported layout, change detection, concurrency, loop prevention, credentials, and CLI usage.

mTLS certificates for Postman CLI runs

The generated CI workflow can run Postman CLI collection runs with client certificates. Pass the cert material as inputs; when a GitHub token and repository context are available, the action persists them as repository secrets (POSTMAN_SSL_CLIENT_CERT_B64, POSTMAN_SSL_CLIENT_KEY_B64, POSTMAN_SSL_CLIENT_PASSPHRASE, POSTMAN_SSL_EXTRA_CA_CERTS_B64) for the generated workflow:

with:
  ssl-client-cert: ${{ secrets.POSTMAN_SSL_CLIENT_CERT_B64 }}
  ssl-client-key: ${{ secrets.POSTMAN_SSL_CLIENT_KEY_B64 }}
  ssl-client-passphrase: ${{ secrets.POSTMAN_SSL_CLIENT_PASSPHRASE }}

Inputs

| Name | Description | Required | Default | | --- | --- | --- | --- | | working-directory | Repository-root-relative directory used for all local inputs and generated artifacts. | no | "" | | generate-ci-workflow | Whether to generate the CI workflow file. Defaults to true at the repository root and false when working-directory is set. | no | | | 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 | | | onboarding-scope | Onboarding scope. Use full for the complete pipeline or spec-only for repository linking and workspace/spec state only. | no | full | | prebuilt-collections-json | Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without a cloud snapshot read. | 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 | | | 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 | private | | 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 | "" | | environments-json | JSON array of environment slugs or full definitions ({slug, values}) to create or replace. Secret-typed values must be empty runtime slots. | 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. For commit-and-push it must identify the checked-out origin. | 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 | [email protected] | | 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 login --with-api-key step in the generated CI workflow (collection run). 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 (a failing key is replaced by one minted from the token); required as the mint source when postman-access-token is omitted. | 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 | "" | | secrets-resolver | Cloud secret store the generated environments seed credential slots for: none (default, no secret-store variables are added), aws (AWS Secrets Manager), azure (Azure Key Vault), or gcp (Google Secret Manager). Must match the secrets-resolver value passed to the bootstrap and smoke-flow actions. | no | none | | 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 for non-fork runs; fork PRs are always gated. 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 |

Outputs

| Name | Description | | --- | --- | | 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. | | 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 | 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 a non-fork branch-strategy legacy run. | | 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. |

Self-contained binary (no npm / no Node)

For CI that cannot install npm or Node — locked-down Jenkins, bare Bitbucket agents, boxes with no package-registry access — a single self-contained executable is published as a GitHub Release asset. It bakes the Node runtime and the full bundle into one file, so the target needs no npm, no Node install, and no package-registry access. It is not network-isolated: the run still needs outbound access to the Postman API/gateway.

VERSION=2.1.10   # example: use a release that carries the binary
ASSET="postman-repo-sync-${VERSION}-linux-x64"
BASE_URL="https://github.com/postman-cs/postman-repo-sync-action/releases/download/v${VERSION}"
curl -fsSLO "${BASE_URL}/${ASSET}"
curl -fsSLO "${BASE_URL}/${ASSET}.sha256"
shasum -a 256 -c "${ASSET}.sha256"
chmod +x "$ASSET"
mv "$ASSET" postman-repo-sync

export POSTMAN_ACCESS_TOKEN="<minted-token>"
./postman-repo-sync --project-name core-payments --workspace-id ws-123 --repo-write-mode commit-only --result-json postman-repo-sync-result.json

Credentials resolve from a CLI flag, then the INPUT_* env var, then a plain POSTMAN_ACCESS_TOKEN / POSTMAN_API_KEY — so Jenkins withCredentials works with no flag. Proxy-only agents must set NODE_USE_ENV_PROXY=1 alongside HTTP_PROXY / HTTPS_PROXY. The binary pulls no extra tooling onto the agent on any path (even with a postman-api-key, which is only used to mint the access token). Two things to know for locked-down runs: the commit modes shell out to git (the binary bundles Node, not git), and with generate-ci-workflow: true (default) the workflow file it writes will — when your CI later runs it — install the Postman CLI from dl-cli.pstmn.io. Current target is linux-x64. Full runbook, credential minting, the complete host allowlist, and a Jenkins pipeline: Self-contained binary.

How it works

The action syncs a Postman workspace into the checked-out repository and can connect the workspace back to that repository:

• Postman Collection v3 multi-file YAML exports under postman/collections/.
• Postman environment exports under postman/environments/.
• .postman/resources.yaml with local-to-cloud resource mappings.
• Optional .postman/workflows.yaml spec-to-collection metadata.
• Optional generated GitHub Actions workflow for Postman CLI smoke and contract runs.
• Optional mock server, cloud monitor, workspace repository link, and system environment associations.

The generated files are intended to be committed when repo-write-mode is commit-only or commit-and-push. Treat postman/ and .postman/ as reviewable source artifacts for the onboarding workflow; commit and review them like any other tracked source.

A typical export looks like:

postman/collections/core-payments/
  collection.yaml
  <folder>.yaml
  <request>.yaml
postman/collections/[Smoke] core-payments/
  collection.yaml
  <folder>.yaml
  <request>.yaml
postman/environments/
  prod.postman_environment.json
.postman/
  resources.yaml

flowchart LR
    subgraph SYNC["repo-sync: once per onboarding run"]
        W["Postman workspace"] -->|"gateway v3 export"| ART["postman/ + .postman/<br/>committed artifacts"]
        ART --> WF["generated CI workflow"]
        W --> MM["mock server +<br/>smoke monitor"]
    end
    subgraph LOOP["customer CI: every push / PR / 6h schedule"]
        WF --> RUN["postman collection run<br/>Smoke then Contract"]
        RES[".postman/resources.yaml<br/>collection UIDs + environment"] --> RUN
        RUN --> API["live API or mock<br/>environment baseUrl"]
        API --> REP["pass/fail per assertion<br/>+ --report-events to<br/>Postman run history"]
    end

This is the execution half of the suite's contract-testing story: bootstrap injects the spec-derived pm.test() assertions into the collections, and the workflow this action generates is what actually runs them against a live target on every push and on schedule. See bootstrap's Contract Enforcement Layers for the full two-layer model.

What the generated CI workflow runs

When CI workflow generation is enabled, the committed GitHub Actions workflow runs on every push and pull request to main and on a six-hour schedule. Each run:

1. Checks out the repository and installs the Postman CLI from the region-appropriate install URL.
2. Logs the Postman CLI in with the POSTMAN_API_KEY repository secret (this action mints and stores that secret when repository write access allows).
3. Resolves the [Smoke] and [Contract] collection UIDs and the environment UID from the committed .postman/resources.yaml, failing fast if any are missing.
4. Decodes optional mTLS client certificates from the POSTMAN_SSL_* secrets and passes them to the runs.
5. Runs the [Smoke] collection and then the [Contract] collection with postman collection run against the resolved environment, with --report-events so results land in the Postman cloud run history, and with CI_ENVIRONMENT (the CI_ENVIRONMENT repository variable, default Production) available to scripts.

A matching Azure DevOps Pipelines template is generated for Azure DevOps repositories. With ci-runner-os: windows, each Smoke and Contract CLI invocation forwards RESPONSE_TIME_THRESHOLD with --env-var; the Azure variable is used when set and otherwise defaults to 10000 milliseconds. GitHub Actions/Linux generation keeps its seeded 2000 millisecond threshold. The assertions those collections execute are generated upstream: the per-check reference is in postman-bootstrap-action's Generated Assertions, and the curated Smoke journey scripts are in postman-smoke-flow-action's Generated Test Scripts.

For commit-and-push, the push target is resolved from current-ref, then GITHUB_HEAD_REF, then GITHUB_REF_NAME. Pull request merge refs are normalized to the PR head branch, but fork pull requests are always gated before credentials or repository writes are attempted. An explicit repo-url must identify the checked-out origin; the action will not redirect a push credential to a different host or repository.

Mocks and monitors: when baseline-collection-id, workspace-id, and at least one environment are available, the action creates or reuses a mock server. When smoke-collection-id is also available, it creates or reuses a cloud smoke monitor unless monitor-type: cli is set. With an empty monitor-cron, a new cloud monitor is created disabled and triggered once per workflow invocation.

Asset reuse priority is explicit inputs (environment-uids-json, mock-url, monitor-id), then live discovery by exact workspace-scoped name, collection UID, and environment UID, then create. The gateway's live published field must match the requested mock-visibility, and explicit URLs must match the expected workspace, collection, and environment. Mismatched or unknown visibility fails closed; private reuse installs the same runtime x-api-key hook as private creation. Under the private default, a previously public mock must be changed to private in Postman or explicitly reused with mock-visibility: public. Creates submit once and reconcile on ambiguous gateway errors; overlapping compatible creates inside one process share a single in-flight promise. Adopted environments are updated to the requested values. Mock environment assignment has no verified patch route, so a mock is reused only when its live environment already matches; mismatches are never claimed as converged. Concurrent jobs against the same workspace can still race because Postman does not expose create idempotency keys—serialize those workflows with GitHub Actions concurrency (or an equivalent CI lock) when duplicate mocks/monitors/environments would be harmful.

Deeper reference:

• Artifact layout and Collection v3 format, including sync modes and versioned releases.
• Credentials: postman-api-key, postman-access-token, credential preflight, GitHub tokens.
• CLI usage: the postman-repo-sync binary for GitLab CI, Bitbucket Pipelines, and Azure DevOps.
• Self-contained binary: the no-npm/no-Node release binary for locked-down agents — install, credential minting, host allowlist, and a Jenkins pipeline.
• Security: supported releases, reporting, and secret-handling expectations.
• Support: where to ask usage questions and what diagnostics to include.
• Release policy: immutable version tags and the rolling-major vN alias.

Resources

• npm package: @postman-cs/onboarding-repo-sync
• Postman API and auth references: Postman API, API authentication, Postman CLI auth, EU data residency
• Postman artifact and runtime references: Collection v3 schema, Postman CLI collection runs, environments, mock servers, monitors

Telemetry

The action sends one anonymous usage event per run (action name/version, outcome, coarse CI metadata; never secrets, spec content, or repo names). Disable with POSTMAN_ACTIONS_TELEMETRY=off or DO_NOT_TRACK=1; route events to your own collector with POSTMAN_ACTIONS_TELEMETRY_ENDPOINT.

License

MIT