@postman-cse/onboarding-repo-sync 0.10.1

package/README.md

@@ -0,0 +1,326 @@
+# postman-repo-sync-action
+
+Public open-alpha GitHub Action that owns Postman-to-repo sync concerns split out of `api-catalog-demo-infra/.github/actions/finalize`.
+
+## Scope
+
+Retained from finalize:
+
+- Create or update Postman environments from runtime URLs.
+- Associate Postman environments to system environments through Bifrost.
+- Create mock servers and smoke monitors from generated collections.
+- Export Postman collections in the Collection v3 multi-file YAML directory structure under `postman/collections/` (e.g., `[Baseline] <name>/collection.yaml`, nested folder and request YAML files). Persist repo variables and export environments into the repository under `postman/` and `.postman/`.
+- Link the Postman workspace to the repository (GitHub or GitLab) through Bifrost.
+- Commit synced artifacts and push them back to the current checked out ref.
+
+Removed from finalize:
+
+- Generate Fern docs or write documentation URLs back to GitHub.
+- Store AWS deployment orchestration concerns in the public action interface.
+- Push directly to `main`.
+
+For existing repositories, use `generate-ci-workflow: false` to avoid touching workflow files, or set `ci-workflow-path` to materialize the generated pipeline under a non-conflicting filename such as `.github/workflows/postman-sync.yml`.
+
+
+### Git provider support
+
+Workspace-to-repository linking via Bifrost supports both **GitHub** and **GitLab** (cloud and self-hosted) repository URLs. When `repo-url` is omitted, the action auto-detects the repository URL from `$GITHUB_REPOSITORY` (GitHub Actions) or `$CI_PROJECT_URL` (GitLab CI). You can also pass an explicit `repo-url` for any git provider.
+
+### mTLS / Client Certificate Support
+
+The generated CI workflow supports client certificates for testing APIs that require mTLS.
+
+On GitHub, set these repository secrets:
+
+- `POSTMAN_SSL_CLIENT_CERT_B64`
+- `POSTMAN_SSL_CLIENT_KEY_B64`
+- `POSTMAN_SSL_CLIENT_PASSPHRASE` (optional)
+- `POSTMAN_SSL_EXTRA_CA_CERTS_B64` (optional)
+
+When you pass the matching inputs to the action with a token that has `secrets:write`, the action can auto-persist these secrets for the generated workflow.
+
+GitLab CI:
+
+```yaml
+variables:
+  POSTMAN_SSL_CLIENT_CERT_B64: $POSTMAN_SSL_CLIENT_CERT_B64
+  POSTMAN_SSL_CLIENT_KEY_B64: $POSTMAN_SSL_CLIENT_KEY_B64
+  POSTMAN_SSL_CLIENT_PASSPHRASE: $POSTMAN_SSL_CLIENT_PASSPHRASE
+  POSTMAN_SSL_EXTRA_CA_CERTS_B64: $POSTMAN_SSL_EXTRA_CA_CERTS_B64
+```
+
+Bitbucket Pipelines:
+
+```yaml
+definitions:
+  variables:
+    POSTMAN_SSL_CLIENT_CERT_B64: "$POSTMAN_SSL_CLIENT_CERT_B64"
+    POSTMAN_SSL_CLIENT_KEY_B64: "$POSTMAN_SSL_CLIENT_KEY_B64"
+    POSTMAN_SSL_CLIENT_PASSPHRASE: "$POSTMAN_SSL_CLIENT_PASSPHRASE"
+    POSTMAN_SSL_EXTRA_CA_CERTS_B64: "$POSTMAN_SSL_EXTRA_CA_CERTS_B64"
+```
+
+> **Note:** Bitbucket secured variables have a size ceiling, so large cert chains may need to be split or stored elsewhere.
+
+Azure DevOps:
+
+```yaml
+steps:
+  - script: npx postman-repo-sync-action
+    env:
+      POSTMAN_SSL_CLIENT_CERT_B64: $(POSTMAN_SSL_CLIENT_CERT_B64)
+      POSTMAN_SSL_CLIENT_KEY_B64: $(POSTMAN_SSL_CLIENT_KEY_B64)
+      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)
+      POSTMAN_SSL_EXTRA_CA_CERTS_B64: $(POSTMAN_SSL_EXTRA_CA_CERTS_B64)
+```
+
+> **Note:** Azure DevOps secret variables must be mapped into step `env`; do not reference them directly on the CLI.
+
+### CLI Usage (Non-GitHub CI)
+
+The `postman-repo-sync` CLI is available for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems that need the repo sync workflow outside GitHub Actions. GitHub Actions users should continue using the `action.yml` interface.
+
+Install it globally:
+
+```bash
+npm install -g postman-repo-sync-action
+```
+
+Basic usage:
+
+```bash
+postman-repo-sync \
+  --project-name core-payments \
+  --workspace-id ws-123 \
+  --baseline-collection-id col-baseline \
+  --smoke-collection-id col-smoke \
+  --contract-collection-id col-contract \
+  --postman-api-key "$POSTMAN_API_KEY" \
+  --result-json ./postman-repo-sync-result.json \
+  --dotenv-path ./postman-repo-sync.env \
+  --repo-write-mode commit-only
+```
+
+The CLI auto-detects the CI provider from environment variables and uses that context to resolve the repository branch, commit SHA, and repo URL. `--repo-write-mode` defaults to `commit-and-push`; use `commit-only` when push credentials are not configured.
+
+JSON is written to stdout. Use `--result-json` to write the same JSON payload to a file, or `--dotenv-path` to emit shell-sourceable `KEY=VALUE` output with the `POSTMAN_REPO_SYNC_` prefix. All logs go to stderr, so stdout stays reserved for JSON output.
+
+GitLab CI:
+
+```yaml
+repo_sync:
+  image: node:20
+  script:
+    - npm install -g postman-repo-sync-action
+    - postman-repo-sync --project-name core-payments --workspace-id ws-123 --baseline-collection-id col-baseline --smoke-collection-id col-smoke --contract-collection-id col-contract --postman-api-key "$POSTMAN_API_KEY" --result-json postman-repo-sync-result.json --dotenv-path postman-repo-sync.env --repo-write-mode commit-and-push
+  artifacts:
+    paths:
+      - postman-repo-sync-result.json
+      - postman-repo-sync.env
+```
+
+Bitbucket Pipelines:
+
+```yaml
+image: node:20
+
+pipelines:
+  default:
+    - step:
+        name: Postman repo sync
+        script:
+          - npm install -g postman-repo-sync-action
+          - postman-repo-sync --project-name core-payments --workspace-id ws-123 --baseline-collection-id col-baseline --smoke-collection-id col-smoke --contract-collection-id col-contract --postman-api-key "$POSTMAN_API_KEY" --result-json postman-repo-sync-result.json --dotenv-path postman-repo-sync.env --repo-write-mode commit-and-push
+        artifacts:
+          - postman-repo-sync-result.json
+          - postman-repo-sync.env
+```
+
+Azure DevOps:
+
+```yaml
+steps:
+  - script: |
+      npm install -g postman-repo-sync-action
+      postman-repo-sync --project-name core-payments --workspace-id ws-123 --baseline-collection-id col-baseline --smoke-collection-id col-smoke --contract-collection-id col-contract --postman-api-key "$(POSTMAN_API_KEY)" --result-json $(Build.ArtifactStagingDirectory)/postman-repo-sync-result.json --dotenv-path $(Build.ArtifactStagingDirectory)/postman-repo-sync.env --repo-write-mode commit-and-push
+    displayName: Postman repo sync
+```
+
+The CLI accepts the same repo-context signals as the action and auto-detects branch, SHA, and repo URL from provider-specific environment variables when available.
+
+## Usage
+
+```yaml
+jobs:
+  repo-sync:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: postman-cs/postman-repo-sync-action@v0
+        with:
+          project-name: core-payments
+          workspace-id: ws-123
+          baseline-collection-id: col-baseline
+          smoke-collection-id: col-smoke
+          contract-collection-id: col-contract
+          environments-json: '["prod","stage"]'
+          system-env-map-json: '{"prod":"uuid-prod","stage":"uuid-stage"}'
+          env-runtime-urls-json: '{"prod":"https://api.example.com","stage":"https://stage-api.example.com"}'
+          environment-uids-json: '{}'
+          repo-write-mode: commit-and-push
+          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+          postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          gh-fallback-token: ${{ secrets.GH_FALLBACK_TOKEN }}
+
+  repo-sync-existing:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: write
+      variables: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: postman-cs/postman-repo-sync-action@v0
+        with:
+          project-name: core-payments
+          workspace-id: ws-123
+          baseline-collection-id: col-baseline
+          smoke-collection-id: col-smoke
+          contract-collection-id: col-contract
+          generate-ci-workflow: false
+          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+```
+
+## Current-ref push semantics
+
+When `repo-write-mode=commit-and-push`, the action pushes back to the current checked out ref instead of hardcoding `main`. Resolution order is `current-ref`, then `GITHUB_HEAD_REF`, then `GITHUB_REF_NAME`. Pull request merge refs are normalized to `GITHUB_HEAD_REF`. Pushes use `HEAD:refs/heads/<resolved-branch>`.
+
+If the action writes `.github/workflows/ci.yml`, provide a credential source that can update workflow files. The action prefers `gh-fallback-token` first for workflow-file pushes, then falls back to `github-token`.
+
+### Collection v3 export
+
+Collections are exported in the Postman Collection v3 format, producing a multi-file YAML directory structure under `postman/collections/`. Each collection (Baseline, Smoke, Contract) gets its own directory containing `collection.yaml` and nested folder/request YAML files. The `.postman/resources.yaml` manifest maps each v3 collection directory to its Postman UID.
+
+## Inputs
+
+| Input | Default | Notes |
+| --- | --- | --- |
+| `generate-ci-workflow` | `true` | Set to `false` for existing repos that already own their CI workflow layout. |
+| `ci-workflow-path` | `.github/workflows/ci.yml` | Redirect generated CI to a non-conflicting path for existing repos. |
+| `project-name` | | Service name used for environments, mock servers, and monitors. |
+| `workspace-id` | | Workspace identifier used for workspace-link and export metadata. |
+| `baseline-collection-id` | | Baseline collection exported into the repo and used for mock generation. |
+| `monitor-type` | `cloud` | Type of monitor to create (`cloud` or `cli`). `cli` uses GitHub Actions cron.
+| `smoke-collection-id` | | Smoke collection used for monitor creation. |
+| `contract-collection-id` | | Contract collection exported into the repo. |
+| `environments-json` | `["prod"]` | Environment slugs to create or update. |
+| `repo-url` | | Explicit repository URL (GitHub or GitLab). Defaults to `https://github.com/$GITHUB_REPOSITORY` on GitHub Actions, or `$CI_PROJECT_URL` on GitLab CI. |
+| `integration-backend` | `bifrost` | Public open-alpha starts with Bifrost only. |
+| `workspace-link-enabled` | `true` | Keeps workspace linking in scope. |
+| `environment-sync-enabled` | `true` | Keeps environment association in scope by default for the open-alpha demonstration path. |
+| `system-env-map-json` | `{}` | JSON map of environment slug to system environment id. |
+| `environment-uids-json` | `{}` | JSON map of environment slug to Postman environment uid. |
+| `env-runtime-urls-json` | `{}` | JSON map of environment slug to runtime base URL. |
+| `artifact-dir` | `postman` | Root directory for exported Postman artifacts. |
+| `repo-write-mode` | `commit-and-push` | Generates files and pushes with current-ref semantics. |
+| `current-ref` | | Optional explicit ref override for detached checkouts. |
+| `committer-name` | `Postman CSE` | Commit author name for sync commits. |
+| `committer-email` | `help@postman.com` | Commit author email for sync commits. |
+| `postman-api-key` | | Postman API key for environment, mock, and monitor work. |
+| `postman-access-token` | | Postman access token for Bifrost and system environment association. |
+| `ssl-client-cert` | | Base64-encoded client certificate for mTLS-enabled API testing. |
+| `ssl-client-key` | | Base64-encoded private key paired with `ssl-client-cert`. |
+| `ssl-client-passphrase` | | Optional passphrase for the client key. |
+| `ssl-extra-ca-certs` | | Base64-encoded extra CA certificates used to trust private certificate chains. |
+| `github-token` | | GitHub token for repo variables and commits. |
+| `gh-fallback-token` | | Fallback GitHub token for workflow-file and variable APIs. |
+| `github-auth-mode` | `github_token_first` | GitHub auth mode for repo variable APIs. |
+| `ci-workflow-base64` | | Optional base64-encoded workflow content that overrides the built-in CI template. |
+
+### Obtaining `postman-api-key`
+
+The `postman-api-key` is a Postman API key (PMAK) used for all standard Postman API operations — creating workspaces, uploading specs, generating collections, exporting artifacts, and managing environments.
+
+**To generate one:**
+
+1. Open the Postman desktop app or web UI.
+2. Go to **Settings** (gear icon) → **Account Settings** → **API Keys**.
+3. Click **Generate API Key**, give it a label, and copy the key (starts with `PMAK-`).
+4. Set it as a GitHub secret:
+   ```bash
+   gh secret set POSTMAN_API_KEY --repo <owner>/<repo>
+   ```
+
+> **Note:** The PMAK is a long-lived key tied to your Postman account. It does not require periodic renewal like the `postman-access-token`.
+
+### Obtaining `postman-access-token` (Open Alpha)
+
+> **⚠️ Open-alpha limitation:** The `postman-access-token` input requires a manually-extracted session token. There is currently no public API to exchange a Postman API key (PMAK) for an access token programmatically. This manual step will be eliminated before GA.
+
+The `postman-access-token` is a Postman session token (`x-access-token`) required for internal API operations that the standard PMAK API key cannot perform — specifically workspace ↔ repo git sync (Bifrost) and system environment associations. Without it, those steps are silently skipped.
+
+**To obtain and configure the token:**
+
+1. **Log in via the Postman CLI** (requires a browser):
+   ```bash
+   postman login
+   ```
+   This opens a browser window for Postman's PKCE OAuth flow. Complete the sign-in.
+
+2. **Extract the access token** from the CLI credential store:
+   ```bash
+   cat ~/.postman/postmanrc | jq -r '.login._profiles[].accessToken'
+   ```
+
+3. **Set it as a GitHub secret** on your repository or organization:
+   ```bash
+   # Repository-level secret
+   gh secret set POSTMAN_ACCESS_TOKEN --repo <owner>/<repo>
+
+   # Organization-level secret (recommended for multi-repo use)
+   gh secret set POSTMAN_ACCESS_TOKEN --org <org> --visibility selected --repos <repo1>,<repo2>
+   ```
+   Paste the token value when prompted.
+
+> **Important:** This token is session-scoped and will expire. When it does, operations that depend on it (workspace linking, system environment associations) will silently degrade. You will need to repeat the login and secret update process. There is no automated refresh mechanism.
+
+> **Note:** `postman login --with-api-key` stores a PMAK — **not** the session token these APIs require. You must use the interactive browser login.
+
+## Outputs
+
+| Output | Meaning |
+| --- | --- |
+| `integration-backend` | Resolved integration backend for the run. |
+| `resolved-current-ref` | Resolved push target based on current-ref semantics. |
+| `workspace-link-status` | `success`, `skipped`, or `failed`. |
+| `environment-sync-status` | `success`, `skipped`, or `failed`. |
+| `environment-uids-json` | JSON map of environment slug to Postman environment uid. |
+| `mock-url` | Created mock server URL. |
+| `monitor-id` | Created smoke monitor UID. |
+| `repo-sync-summary-json` | JSON summary of repo materialization and workspace sync outputs. |
+| `commit-sha` | Commit SHA produced by repo-write-mode when a sync commit is created. |
+
+## Local development
+
+```bash
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+`npm run build` produces the committed `dist/index.cjs` action bundle used by `action.yml`.
+
+## Open-Alpha Release Strategy
+
+- Open-alpha channel tags use `v0.x.y`.
+- Consumers can pin immutable tags such as `v0.2.0` for reproducibility.
+- Moving tag `v0` is used only as the rolling open-alpha channel.
+
+## REST Migration Seam
+
+The public input and output contract is backend-neutral. `integration-backend` defaults to `bifrost`, and backend-specific metadata remains internal so a future REST implementation can replace the backend without changing caller workflow syntax.

package/action.yml

@@ -0,0 +1,148 @@
+name: postman-repo-sync-action
+description: Sync exported Postman artifacts into a repository and expose open-alpha workspace-link and environment-sync contract outputs.
+inputs:
+
+  generate-ci-workflow:
+    description: Whether to generate the CI workflow file
+    required: false
+    default: "true"
+  ci-workflow-path:
+    description: Path to write the generated CI workflow file
+    required: false
+    default: .github/workflows/ci.yml
+  project-name:
+    description: Service project name used for environment, mock, and monitor naming.
+    required: true
+  workspace-id:
+    description: Postman workspace ID used for workspace-link and export metadata.
+    required: false
+  baseline-collection-id:
+    description: Baseline collection ID used for exported artifacts and mock server creation.
+    required: false
+  monitor-type:
+    description: Type of monitor to create ("cloud" or "cli"). "cli" will skip cloud monitor creation and rely on the CI workflow.
+    required: false
+    default: cloud
+  smoke-collection-id:
+    description: Smoke collection ID used for monitor creation.
+    required: false
+  contract-collection-id:
+    description: Contract collection ID used for exported artifacts.
+    required: false
+  monitor-id:
+    description: Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one.
+    required: false
+  mock-url:
+    description: Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.
+    required: false
+  monitor-cron:
+    description: Cron expression for monitor scheduling (e.g. '0 */6 * * *'). When empty, the monitor is created in a disabled state.
+    required: false
+    default: ""
+  environments-json:
+    description: JSON array of environment slugs to create or update.
+    required: false
+    default: '["prod"]'
+  repo-url:
+    description: 'Explicit repository URL (GitHub or GitLab). Defaults to https://github.com/$GITHUB_REPOSITORY on GitHub Actions, or $CI_PROJECT_URL on GitLab CI, when omitted.'
+    required: false
+  integration-backend:
+    description: Integration backend for workspace linking and environment sync.
+    required: false
+    default: bifrost
+  workspace-link-enabled:
+    description: Enable workspace linking.
+    required: false
+    default: 'true'
+  environment-sync-enabled:
+    description: Enable association of Postman environments to system environments.
+    required: false
+    default: 'true'
+  system-env-map-json:
+    description: JSON map of environment slug to system environment id.
+    required: false
+    default: '{}'
+  environment-uids-json:
+    description: JSON map of environment slug to Postman environment uid.
+    required: false
+    default: '{}'
+  env-runtime-urls-json:
+    description: JSON map of environment slug to runtime base URL.
+    required: false
+    default: '{}'
+  artifact-dir:
+    description: Root directory for exported Postman artifacts.
+    required: false
+    default: postman
+  repo-write-mode:
+    description: Repo mutation mode for generated artifacts and workflow files.
+    required: false
+    default: commit-and-push
+  current-ref:
+    description: Explicit ref override for push-changes when the checkout is detached.
+    required: false
+  committer-name:
+    description: Git committer name for sync commits.
+    required: false
+    default: Postman CSE
+  committer-email:
+    description: Git committer email for sync commits.
+    required: false
+    default: help@postman.com
+  postman-api-key:
+    description: Postman API key used for environment, mock, and monitor operations.
+    required: false
+  postman-access-token:
+    description: Postman access token used for Bifrost and system environment association.
+    required: false
+  github-token:
+    description: GitHub token used for repo variable persistence and commits.
+    required: false
+  gh-fallback-token:
+    description: Fallback token for repository variable APIs and workflow-file pushes.
+    required: false
+  github-auth-mode:
+    description: GitHub auth mode for repository variable APIs.
+    required: false
+    default: github_token_first
+  org-mode:
+    description: Whether the Postman team uses org-mode. When true, x-entity-team-id header is included in Bifrost proxy calls. Non-org teams must omit this header.
+    required: false
+    default: 'false'
+  ci-workflow-base64:
+    description: Optional base64-encoded ci.yml content. Defaults to the built-in template.
+    required: false
+  ssl-client-cert:
+    description: Base64-encoded PEM client certificate for Postman CLI mTLS runs.
+    required: false
+  ssl-client-key:
+    description: Base64-encoded PEM client private key for Postman CLI mTLS runs.
+    required: false
+  ssl-client-passphrase:
+    description: Optional passphrase for encrypted ssl-client-key.
+    required: false
+  ssl-extra-ca-certs:
+    description: Optional base64-encoded PEM CA certificate bundle for custom trust.
+    required: false
+outputs:
+  integration-backend:
+    description: Resolved integration backend for the open-alpha run.
+  resolved-current-ref:
+    description: Resolved push target based on current-ref semantics.
+  workspace-link-status:
+    description: Whether workspace linking succeeded, was skipped, or failed.
+  environment-sync-status:
+    description: Whether environment sync succeeded, was skipped, or failed.
+  environment-uids-json:
+    description: JSON map of environment slug to Postman environment uid.
+  mock-url:
+    description: Created or reused mock server URL.
+  monitor-id:
+    description: Created or reused smoke monitor ID.
+  repo-sync-summary-json:
+    description: JSON summary of repo materialization and workspace sync outputs.
+  commit-sha:
+    description: Commit SHA produced by repo-write-mode, if any.
+runs:
+  using: node20
+  main: dist/index.cjs