@postman-cse/onboarding-repo-sync 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +167 -277
  3. package/action.yml +10 -3
  4. package/dist/cli.cjs +368 -132
  5. package/dist/index.cjs +360 -128
  6. package/package.json +12 -2
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Postman, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,164 +1,28 @@
1
1
  # postman-repo-sync-action
2
2
 
3
- Public open-alpha GitHub Action that owns Postman-to-repo sync concerns split out of `api-catalog-demo-infra/.github/actions/finalize`.
3
+ Sync Postman workspace assets into a repository and optionally connect the workspace back to that repository.
4
4
 
5
- ## Scope
5
+ Use this action when a repo should contain the Postman artifacts needed for CI, reviews, and repeatable API test runs:
6
6
 
7
- Retained from finalize:
7
+ - Postman Collection v3 multi-file YAML exports under `postman/collections/`.
8
+ - Postman environment exports under `postman/environments/`.
9
+ - `.postman/resources.yaml` with local-to-cloud resource mappings.
10
+ - Optional `.postman/workflows.yaml` spec-to-collection metadata.
11
+ - Optional generated GitHub Actions workflow for Postman CLI smoke and contract runs.
12
+ - Optional mock server, cloud monitor, workspace repository link, and system environment associations.
8
13
 
9
- - Create or update Postman environments from runtime URLs.
10
- - Associate Postman environments to system environments through Bifrost.
11
- - Create mock servers and smoke monitors from generated collections.
12
- - 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), and export environments plus `.postman/resources.yaml` into the repository.
13
- - Link the Postman workspace to the repository (GitHub or GitLab) through Bifrost.
14
- - Commit synced artifacts and push them back to the current checked out ref.
15
-
16
- Removed from finalize:
17
-
18
- - Generate Fern docs or write documentation URLs back to GitHub.
19
- - Store AWS deployment orchestration concerns in the public action interface.
20
- - Push directly to `main`.
21
-
22
- 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`.
23
-
24
-
25
- ### Git provider support
26
-
27
- 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.
28
-
29
- ### mTLS / Client Certificate Support
30
-
31
- The generated CI workflow supports client certificates for testing APIs that require mTLS.
32
-
33
- On GitHub, set these repository secrets:
34
-
35
- - `POSTMAN_SSL_CLIENT_CERT_B64`
36
- - `POSTMAN_SSL_CLIENT_KEY_B64`
37
- - `POSTMAN_SSL_CLIENT_PASSPHRASE` (optional)
38
- - `POSTMAN_SSL_EXTRA_CA_CERTS_B64` (optional)
39
-
40
- 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.
41
-
42
- GitLab CI:
43
-
44
- ```yaml
45
- variables:
46
- POSTMAN_SSL_CLIENT_CERT_B64: $POSTMAN_SSL_CLIENT_CERT_B64
47
- POSTMAN_SSL_CLIENT_KEY_B64: $POSTMAN_SSL_CLIENT_KEY_B64
48
- POSTMAN_SSL_CLIENT_PASSPHRASE: $POSTMAN_SSL_CLIENT_PASSPHRASE
49
- POSTMAN_SSL_EXTRA_CA_CERTS_B64: $POSTMAN_SSL_EXTRA_CA_CERTS_B64
50
- ```
51
-
52
- Bitbucket Pipelines:
53
-
54
- ```yaml
55
- definitions:
56
- variables:
57
- POSTMAN_SSL_CLIENT_CERT_B64: "$POSTMAN_SSL_CLIENT_CERT_B64"
58
- POSTMAN_SSL_CLIENT_KEY_B64: "$POSTMAN_SSL_CLIENT_KEY_B64"
59
- POSTMAN_SSL_CLIENT_PASSPHRASE: "$POSTMAN_SSL_CLIENT_PASSPHRASE"
60
- POSTMAN_SSL_EXTRA_CA_CERTS_B64: "$POSTMAN_SSL_EXTRA_CA_CERTS_B64"
61
- ```
62
-
63
- > **Note:** Bitbucket secured variables have a size ceiling, so large cert chains may need to be split or stored elsewhere.
64
-
65
- Azure DevOps:
66
-
67
- ```yaml
68
- steps:
69
- - script: npx postman-repo-sync-action
70
- env:
71
- POSTMAN_SSL_CLIENT_CERT_B64: $(POSTMAN_SSL_CLIENT_CERT_B64)
72
- POSTMAN_SSL_CLIENT_KEY_B64: $(POSTMAN_SSL_CLIENT_KEY_B64)
73
- POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)
74
- POSTMAN_SSL_EXTRA_CA_CERTS_B64: $(POSTMAN_SSL_EXTRA_CA_CERTS_B64)
75
- ```
76
-
77
- > **Note:** Azure DevOps secret variables must be mapped into step `env`; do not reference them directly on the CLI.
78
-
79
- ### CLI Usage (Non-GitHub CI)
80
-
81
- 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.
82
-
83
- Install it globally:
84
-
85
- ```bash
86
- npm install -g postman-repo-sync-action
87
- ```
88
-
89
- Basic usage:
90
-
91
- ```bash
92
- postman-repo-sync \
93
- --project-name core-payments \
94
- --workspace-id ws-123 \
95
- --baseline-collection-id col-baseline \
96
- --smoke-collection-id col-smoke \
97
- --contract-collection-id col-contract \
98
- --postman-api-key "$POSTMAN_API_KEY" \
99
- --result-json ./postman-repo-sync-result.json \
100
- --dotenv-path ./postman-repo-sync.env \
101
- --repo-write-mode commit-only
102
- ```
103
-
104
- 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.
105
-
106
- 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.
107
-
108
- GitLab CI:
109
-
110
- ```yaml
111
- repo_sync:
112
- image: node:20
113
- script:
114
- - npm install -g postman-repo-sync-action
115
- - 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
116
- artifacts:
117
- paths:
118
- - postman-repo-sync-result.json
119
- - postman-repo-sync.env
120
- ```
121
-
122
- Bitbucket Pipelines:
123
-
124
- ```yaml
125
- image: node:20
126
-
127
- pipelines:
128
- default:
129
- - step:
130
- name: Postman repo sync
131
- script:
132
- - npm install -g postman-repo-sync-action
133
- - 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
134
- artifacts:
135
- - postman-repo-sync-result.json
136
- - postman-repo-sync.env
137
- ```
138
-
139
- Azure DevOps:
140
-
141
- ```yaml
142
- steps:
143
- - script: |
144
- npm install -g postman-repo-sync-action
145
- 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
146
- displayName: Postman repo sync
147
- ```
148
-
149
- 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.
150
-
151
- ## Usage
14
+ ## Quick Start
152
15
 
153
16
  ```yaml
154
17
  jobs:
155
18
  repo-sync:
156
19
  runs-on: ubuntu-latest
157
20
  permissions:
158
- actions: write
159
21
  contents: write
22
+ actions: write
160
23
  steps:
161
24
  - uses: actions/checkout@v4
25
+
162
26
  - uses: postman-cs/postman-repo-sync-action@v0
163
27
  with:
164
28
  project-name: core-payments
@@ -167,172 +31,208 @@ jobs:
167
31
  smoke-collection-id: col-smoke
168
32
  contract-collection-id: col-contract
169
33
  environments-json: '["prod","stage"]'
170
- system-env-map-json: '{"prod":"uuid-prod","stage":"uuid-stage"}'
171
34
  env-runtime-urls-json: '{"prod":"https://api.example.com","stage":"https://stage-api.example.com"}'
172
- environment-uids-json: '{}'
173
- repo-write-mode: commit-and-push
174
35
  postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
175
36
  postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
176
37
  github-token: ${{ secrets.GITHUB_TOKEN }}
177
- gh-fallback-token: ${{ secrets.GH_FALLBACK_TOKEN }}
38
+ ```
178
39
 
179
- repo-sync-existing:
180
- runs-on: ubuntu-latest
181
- permissions:
182
- actions: write
183
- contents: write
184
- variables: write
185
- steps:
186
- - uses: actions/checkout@v4
187
- - uses: postman-cs/postman-repo-sync-action@v0
188
- with:
189
- project-name: core-payments
190
- workspace-id: ws-123
191
- baseline-collection-id: col-baseline
192
- smoke-collection-id: col-smoke
193
- contract-collection-id: col-contract
194
- generate-ci-workflow: false
195
- postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
40
+ For existing repositories that already own their CI workflow, disable workflow generation:
41
+
42
+ ```yaml
43
+ with:
44
+ generate-ci-workflow: false
196
45
  ```
197
46
 
198
- ## Current-ref push semantics
47
+ Or write the generated workflow somewhere other than `.github/workflows/ci.yml`:
199
48
 
200
- 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>`.
49
+ ```yaml
50
+ with:
51
+ ci-workflow-path: .github/workflows/postman-sync.yml
52
+ ```
201
53
 
202
- 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`.
54
+ ## Requirements
203
55
 
204
- ### Collection v3 export
56
+ - `actions/checkout` must run before this action.
57
+ - `project-name` is required.
58
+ - Provide a valid `postman-api-key`, or provide `postman-access-token` so the action can generate one.
59
+ - `contents: write` is required when `repo-write-mode` commits files.
60
+ - `actions: write` is required when the action writes workflow files.
61
+ - `gh-fallback-token` is recommended when the default `GITHUB_TOKEN` cannot update workflow files or repository secrets.
205
62
 
206
- 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.
63
+ `postman-access-token` is required for workspace-to-repository linking, system environment association, and API key generation. If it is omitted, those integration steps are skipped and the remaining artifact sync can still run with `postman-api-key`.
207
64
 
208
- The generated CI workflow reads `.postman/resources.yaml` directly to resolve the smoke/contract collection IDs and environment ID for Postman CLI runs. It does not depend on repository variables for those asset mappings.
65
+ ## What Gets Written
209
66
 
210
- Folder and request **names are truncated to 120 characters** per path segment when writing files (with an ellipsis). That avoids `ENAMETOOLONG` when Postman item names are very long (for example, copied from long OpenAPI operation summaries).
67
+ The default artifact root is `postman/`. The action ensures these directories exist:
211
68
 
212
- ### Lifecycle and versioning
69
+ - `postman/collections`
70
+ - `postman/environments`
71
+ - `postman/flows`
72
+ - `postman/globals`
73
+ - `postman/mocks`
74
+ - `postman/specs`
213
75
 
214
- `collection-sync-mode` controls collection lifecycle behavior:
76
+ Collections are exported as Collection v3 multi-file YAML directories, for example:
215
77
 
216
- - `refresh` (default): always refresh assets and rewrite `.postman/resources.yaml` for the checked-out ref.
217
- - `reuse`: reuse existing assets from explicit inputs or the checked-out ref's `.postman/resources.yaml`.
218
- - `version`: require a release label (`release-label` input or `github-ref-name`), suffix collection export directories and mock/monitor names with that release label, and reuse only the checked-out ref's `.postman/resources.yaml` mappings.
78
+ ```text
79
+ postman/collections/[Smoke] core-payments/
80
+ collection.yaml
81
+ <folder>.yaml
82
+ <request>.yaml
83
+ ```
219
84
 
220
- `spec-sync-mode` supports `update` (default) and `version`. If either sync mode is `version`, this action requires a derived or explicit release label.
85
+ The action also writes `.postman/resources.yaml`. The generated CI workflow reads that file to resolve smoke collection, contract collection, and environment IDs for Postman CLI runs.
221
86
 
222
- ## Inputs
87
+ Long Postman folder and request names are truncated to 120 characters per path segment when files are written.
223
88
 
224
- | Input | Default | Notes |
225
- | --- | --- | --- |
226
- | `generate-ci-workflow` | `true` | Set to `false` for existing repos that already own their CI workflow layout. |
227
- | `ci-workflow-path` | `.github/workflows/ci.yml` | Redirect generated CI to a non-conflicting path for existing repos. |
228
- | `project-name` | | Service name used for environments, mock servers, and monitors. |
229
- | `workspace-id` | | Workspace identifier used for workspace-link and export metadata. |
230
- | `baseline-collection-id` | | Baseline collection exported into the repo and used for mock generation. |
231
- | `monitor-type` | `cloud` | Type of monitor to create (`cloud` or `cli`). `cli` uses GitHub Actions cron. |
232
- | `smoke-collection-id` | | Smoke collection used for monitor creation. |
233
- | `contract-collection-id` | | Contract collection exported into the repo. |
234
- | `collection-sync-mode` | `refresh` | Collection lifecycle mode: `refresh`, `reuse`, or `version`. |
235
- | `spec-sync-mode` | `update` | Spec lifecycle mode: `update` or `version`. |
236
- | `release-label` | | Optional release label for versioned naming. Falls back to `github-ref-name` when omitted. |
237
- | `environments-json` | `["prod"]` | Environment slugs to create or update. |
238
- | `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. |
239
- | `integration-backend` | `bifrost` | Public open-alpha starts with Bifrost only. |
240
- | `workspace-link-enabled` | `true` | Keeps workspace linking in scope. |
241
- | `environment-sync-enabled` | `true` | Keeps environment association in scope by default for the open-alpha demonstration path. |
242
- | `system-env-map-json` | `{}` | JSON map of environment slug to system environment id. |
243
- | `environment-uids-json` | `{}` | Optional explicit JSON map of environment slug to Postman environment uid. |
244
- | `env-runtime-urls-json` | `{}` | JSON map of environment slug to runtime base URL. |
245
- | `artifact-dir` | `postman` | Root directory for exported Postman artifacts. |
246
- | `repo-write-mode` | `commit-and-push` | Generates files and pushes with current-ref semantics. |
247
- | `current-ref` | | Optional explicit ref override for detached checkouts. |
248
- | `committer-name` | `Postman CSE` | Commit author name for sync commits. |
249
- | `committer-email` | `help@postman.com` | Commit author email for sync commits. |
250
- | `postman-api-key` | | Postman API key for environment, mock, and monitor work. |
251
- | `postman-access-token` | | Postman access token for Bifrost and system environment association. |
252
- | `ssl-client-cert` | | Base64-encoded client certificate for mTLS-enabled API testing. |
253
- | `ssl-client-key` | | Base64-encoded private key paired with `ssl-client-cert`. |
254
- | `ssl-client-passphrase` | | Optional passphrase for the client key. |
255
- | `ssl-extra-ca-certs` | | Base64-encoded extra CA certificates used to trust private certificate chains. |
256
- | `github-token` | | GitHub token for commits, workflow updates, and optional secret persistence. |
257
- | `gh-fallback-token` | | Fallback GitHub token for workflow-file and variable APIs. |
258
- | `ci-workflow-base64` | | Optional base64-encoded workflow content that overrides the built-in CI template. |
89
+ When a local OpenAPI spec is found, `.postman/resources.yaml` records it under `localResources.specs`. If `spec-id` and an unambiguous local spec are available, the action also maps the spec under `cloudResources.specs`. When a mapped spec and exported collections are both present, `.postman/workflows.yaml` is written with `syncSpecToCollection` metadata.
90
+
91
+ ## Repository Writes
92
+
93
+ `repo-write-mode` controls repository mutation:
94
+
95
+ | Mode | Behavior |
96
+ | --- | --- |
97
+ | `commit-and-push` | Commit generated files and push them back to the current checked out ref. |
98
+ | `commit-only` | Commit generated files without pushing. Use this for customer-managed PR workflows. |
99
+ | `none` | Write files in the workspace only. |
100
+
101
+ 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. Pushes use `HEAD:refs/heads/<resolved-branch>`.
102
+
103
+ If branch protection requires pull requests, run on a temporary branch with `repo-write-mode: commit-only`, then create the PR in a later workflow step.
259
104
 
260
- ### Contract smoke monitoring
105
+ ## Sync Modes
261
106
 
262
- This repo includes `.github/workflows/contract-smoke.yml`, a scheduled live contract check for the Postman and Bifrost endpoints used by repo-sync.
107
+ `collection-sync-mode` controls collection lifecycle:
263
108
 
264
- Configure these repository secrets before enabling the workflow:
109
+ | Mode | Behavior |
110
+ | --- | --- |
111
+ | `refresh` | Refresh exports and rewrite resource mappings for the current ref. |
112
+ | `reuse` | Reuse explicit IDs or IDs already present in `.postman/resources.yaml`. |
113
+ | `version` | Require a release label and suffix exported collection directories, mock names, and monitor names with that label. |
114
+
115
+ `spec-sync-mode` supports:
265
116
 
266
- - `SMOKE_ORG_API_KEY`
267
- - `SMOKE_ORG_ACCESS_TOKEN`
268
- - `SMOKE_NON_ORG_API_KEY`
117
+ | Mode | Behavior |
118
+ | --- | --- |
119
+ | `update` | Keep the current spec mapping updated. |
120
+ | `version` | Require a release label and use versioned metadata. |
269
121
 
270
- The smoke workflow verifies `/me`, `/teams`, and Bifrost API key creation so upstream auth or response-shape changes are caught before they break repo-sync runs.
122
+ If either mode is `version`, provide `release-label` or run on a ref name that can be used as the release label.
271
123
 
272
- ### Obtaining `postman-api-key`
124
+ ## Monitoring And Mocks
273
125
 
274
- 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.
126
+ When `baseline-collection-id`, `workspace-id`, and at least one environment are available, the action creates or reuses a mock server.
275
127
 
276
- **To generate one:**
128
+ When `smoke-collection-id`, `workspace-id`, and at least one environment are available, the action creates or reuses a cloud smoke monitor unless `monitor-type: cli` is set. If `monitor-cron` is empty, a new cloud monitor is created disabled.
277
129
 
278
- 1. Open the Postman desktop app or web UI.
279
- 2. Go to **Settings** (gear icon) → **Account Settings** → **API Keys**.
280
- 3. Click **Generate API Key**, give it a label, and copy the key (starts with `PMAK-`).
281
- 4. Set it as a GitHub secret:
282
- ```bash
283
- gh secret set POSTMAN_API_KEY --repo <owner>/<repo>
284
- ```
130
+ Use `mock-url` or `monitor-id` to force reuse of existing assets.
285
131
 
286
- > **Note:** The PMAK is a long-lived key tied to your Postman account. It does not require periodic renewal like the `postman-access-token`.
132
+ ## mTLS
287
133
 
288
- ### Obtaining `postman-access-token` (Open Alpha)
134
+ The generated CI workflow can run Postman CLI with client certificates. Set these GitHub repository secrets:
289
135
 
290
- > **⚠️ 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.
136
+ - `POSTMAN_SSL_CLIENT_CERT_B64`
137
+ - `POSTMAN_SSL_CLIENT_KEY_B64`
138
+ - `POSTMAN_SSL_CLIENT_PASSPHRASE` (optional)
139
+ - `POSTMAN_SSL_EXTRA_CA_CERTS_B64` (optional)
291
140
 
292
- 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.
141
+ You can also pass the matching action inputs. When `ssl-client-cert` is provided and a GitHub token/repository context is available, the action attempts to persist those values as repository secrets for the generated workflow.
293
142
 
294
- **To obtain and configure the token:**
143
+ ## CLI
295
144
 
296
- 1. **Log in via the Postman CLI** (requires a browser):
297
- ```bash
298
- postman login
299
- ```
300
- This opens a browser window for Postman's PKCE OAuth flow. Complete the sign-in.
145
+ The package also ships a `postman-repo-sync` binary for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems.
301
146
 
302
- 2. **Extract the access token** from the CLI credential store:
303
- ```bash
304
- cat ~/.postman/postmanrc | jq -r '.login._profiles[].accessToken'
305
- ```
147
+ ```bash
148
+ npm install -g @postman-cse/onboarding-repo-sync
306
149
 
307
- 3. **Set it as a GitHub secret** on your repository or organization:
308
- ```bash
309
- # Repository-level secret
310
- gh secret set POSTMAN_ACCESS_TOKEN --repo <owner>/<repo>
150
+ postman-repo-sync \
151
+ --project-name core-payments \
152
+ --workspace-id ws-123 \
153
+ --baseline-collection-id col-baseline \
154
+ --smoke-collection-id col-smoke \
155
+ --contract-collection-id col-contract \
156
+ --postman-api-key "$POSTMAN_API_KEY" \
157
+ --result-json postman-repo-sync-result.json \
158
+ --dotenv-path postman-repo-sync.env \
159
+ --repo-write-mode commit-only
160
+ ```
311
161
 
312
- # Organization-level secret (recommended for multi-repo use)
313
- gh secret set POSTMAN_ACCESS_TOKEN --org <org> --visibility selected --repos <repo1>,<repo2>
314
- ```
315
- Paste the token value when prompted.
162
+ The CLI auto-detects repository URL, branch, and SHA from common CI environment variables. It writes JSON to stdout, writes the same JSON to `--result-json`, and optionally writes shell-sourceable `POSTMAN_REPO_SYNC_*` values to `--dotenv-path`. Logs go to stderr.
316
163
 
317
- > **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.
164
+ ## Inputs
318
165
 
319
- > **Note:** `postman login --with-api-key` stores a PMAK — **not** the session token these APIs require. You must use the interactive browser login.
166
+ | Input | Default | Notes |
167
+ | --- | --- | --- |
168
+ | `project-name` | | Required. Service name used for environments, mock servers, and monitors. |
169
+ | `workspace-id` | | Postman workspace ID. Can be resolved from `.postman/resources.yaml` when available. |
170
+ | `baseline-collection-id` | | Baseline collection exported into the repo and used for mock server creation. |
171
+ | `smoke-collection-id` | | Smoke collection used for monitor creation and generated CI. |
172
+ | `contract-collection-id` | | Contract collection exported into the repo and used for generated CI. |
173
+ | `environments-json` | `["prod"]` | JSON array of environment slugs to create or update. |
174
+ | `env-runtime-urls-json` | `{}` | JSON map of environment slug to runtime base URL. |
175
+ | `environment-uids-json` | `{}` | JSON map of environment slug to existing Postman environment UID. |
176
+ | `system-env-map-json` | `{}` | JSON map of environment slug to system environment ID. |
177
+ | `repo-url` | Auto-detected | Explicit repository URL for workspace linking. Auto-detected from common GitHub, GitLab, Bitbucket, and Azure DevOps CI variables when available. |
178
+ | `artifact-dir` | `postman` | Root directory for exported artifacts. |
179
+ | `repo-write-mode` | `commit-and-push` | `commit-and-push`, `commit-only`, or `none`. |
180
+ | `current-ref` | | Explicit branch/ref override for push target resolution. |
181
+ | `generate-ci-workflow` | `true` | Whether to write the generated CI workflow. |
182
+ | `ci-workflow-path` | `.github/workflows/ci.yml` | Path for the generated CI workflow. |
183
+ | `ci-workflow-base64` | | Base64-encoded workflow content that replaces the built-in template. |
184
+ | `collection-sync-mode` | `refresh` | `refresh`, `reuse`, or `version`. |
185
+ | `spec-sync-mode` | `update` | `update` or `version`. |
186
+ | `release-label` | | Label used for versioned collection/spec sync. |
187
+ | `spec-id` | | Cloud spec UID to persist in `.postman/resources.yaml`. |
188
+ | `spec-path` | | Repo-root-relative local spec path to use for metadata. |
189
+ | `monitor-type` | `cloud` | `cloud` creates/reuses a cloud monitor; `cli` skips cloud monitor creation. |
190
+ | `monitor-id` | | Existing smoke monitor ID to validate and reuse. |
191
+ | `mock-url` | | Existing mock server URL to reuse. |
192
+ | `monitor-cron` | | Cron expression for cloud monitor scheduling. Empty creates a disabled monitor. |
193
+ | `workspace-link-enabled` | `true` | Enable workspace-to-repository linking. Requires `postman-access-token`. |
194
+ | `environment-sync-enabled` | `true` | Enable system environment association. Requires `postman-access-token`. |
195
+ | `integration-backend` | `bifrost` | Backend used for workspace linking and environment association. |
196
+ | `org-mode` | `false` | Include `x-entity-team-id` for org-mode Bifrost calls. |
197
+ | `postman-api-key` | | Postman API key for standard Postman API operations. |
198
+ | `postman-access-token` | | Postman session access token for integration operations and API key generation. |
199
+ | `github-token` | | Token for commits, pushes, workflow updates, and secret persistence. |
200
+ | `gh-fallback-token` | | Preferred fallback token for workflow-file pushes and secret persistence. |
201
+ | `committer-name` | `Postman CSE` | Git committer name for sync commits. |
202
+ | `committer-email` | `help@postman.com` | Git committer email for sync commits. |
203
+ | `ssl-client-cert` | | Base64-encoded PEM client certificate. |
204
+ | `ssl-client-key` | | Base64-encoded PEM private key. Required with `ssl-client-cert`. |
205
+ | `ssl-client-passphrase` | | Optional private-key passphrase. |
206
+ | `ssl-extra-ca-certs` | | Optional base64-encoded PEM CA bundle. |
320
207
 
321
208
  ## Outputs
322
209
 
323
210
  | Output | Meaning |
324
211
  | --- | --- |
325
- | `integration-backend` | Resolved integration backend for the run. |
326
- | `resolved-current-ref` | Resolved push target based on current-ref semantics. |
212
+ | `integration-backend` | Resolved integration backend. |
213
+ | `resolved-current-ref` | Branch used as the push target for `commit-and-push`. |
327
214
  | `workspace-link-status` | `success`, `skipped`, or `failed`. |
328
215
  | `environment-sync-status` | `success`, `skipped`, or `failed`. |
329
- | `environment-uids-json` | JSON map of environment slug to Postman environment uid. |
330
- | `mock-url` | Created mock server URL. |
331
- | `monitor-id` | Created smoke monitor UID. |
332
- | `repo-sync-summary-json` | JSON summary of repo materialization and workspace sync outputs. |
333
- | `commit-sha` | Commit SHA produced by repo-write-mode when a sync commit is created. |
216
+ | `environment-uids-json` | JSON map of environment slug to Postman environment UID. |
217
+ | `mock-url` | Created or reused mock server URL. |
218
+ | `monitor-id` | Created or reused smoke monitor ID. |
219
+ | `repo-sync-summary-json` | JSON summary of commit, environment, mock, monitor, push, and integration state. |
220
+ | `commit-sha` | Commit SHA produced by `repo-write-mode`, when a commit is created. |
221
+
222
+ ## Credentials
223
+
224
+ Create a Postman API key in Postman under **Settings -> Account Settings -> API Keys**, then store it as `POSTMAN_API_KEY`.
225
+
226
+ The `postman-access-token` value is a session token used for integration APIs that are not covered by PMAK. To obtain it:
334
227
 
335
- ## Local development
228
+ ```bash
229
+ postman login
230
+ cat ~/.postman/postmanrc | jq -r '.login._profiles[].accessToken'
231
+ ```
232
+
233
+ Store that value as `POSTMAN_ACCESS_TOKEN`. It expires with the Postman session and must be refreshed when integration steps start skipping or failing because of authentication.
234
+
235
+ ## Local Development
336
236
 
337
237
  ```bash
338
238
  npm install
@@ -341,14 +241,4 @@ npm run typecheck
341
241
  npm run build
342
242
  ```
343
243
 
344
- `npm run build` produces the committed `dist/index.cjs` action bundle used by `action.yml`.
345
-
346
- ## Open-Alpha Release Strategy
347
-
348
- - Open-alpha channel tags use `v0.x.y`.
349
- - Consumers can pin immutable tags such as `v0.2.0` for reproducibility.
350
- - Moving tag `v0` is used only as the rolling open-alpha channel.
351
-
352
- ## REST Migration Seam
353
-
354
- 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.
244
+ `npm run build` produces the committed `dist/index.cjs` action bundle used by `action.yml` and `dist/cli.cjs` for the CLI.
package/action.yml CHANGED
@@ -30,7 +30,7 @@ inputs:
30
30
  description: Contract collection ID used for exported artifacts.
31
31
  required: false
32
32
  collection-sync-mode:
33
- description: Collection sync lifecycle mode (refresh, reuse, or version).
33
+ description: Collection sync lifecycle mode (refresh or version).
34
34
  required: false
35
35
  default: refresh
36
36
  spec-sync-mode:
@@ -47,7 +47,7 @@ inputs:
47
47
  description: Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.
48
48
  required: false
49
49
  monitor-cron:
50
- description: Cron expression for monitor scheduling (e.g. '0 */6 * * *'). When empty, the monitor is created in a disabled state.
50
+ description: 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).
51
51
  required: false
52
52
  default: ""
53
53
  environments-json:
@@ -134,6 +134,13 @@ inputs:
134
134
  spec-id:
135
135
  description: Spec UID from bootstrap, persisted into .postman/resources.yaml cloudResources.
136
136
  required: false
137
+ spec-path:
138
+ description: Optional repo-root-relative path to the local spec file for resources/workflows metadata.
139
+ required: false
140
+ postman-stack:
141
+ description: Postman stack profile.
142
+ required: false
143
+ default: prod
137
144
  outputs:
138
145
  integration-backend:
139
146
  description: Resolved integration backend for the open-alpha run.
@@ -154,5 +161,5 @@ outputs:
154
161
  commit-sha:
155
162
  description: Commit SHA produced by repo-write-mode, if any.
156
163
  runs:
157
- using: node20
164
+ using: node24
158
165
  main: dist/index.cjs