@postman-cs/onboarding-repo-sync 2.9.3
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.
- package/LICENSE +21 -0
- package/README.md +339 -0
- package/action.yml +243 -0
- package/dist/action.cjs +122383 -0
- package/dist/cli.cjs +121203 -0
- package/dist/index.cjs +122446 -0
- package/package.json +77 -0
- package/scripts/verify-release-artifacts.mjs +239 -0
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
ADDED
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
# Postman Onboarding: Repo Sync
|
|
2
|
+
|
|
3
|
+
[](https://github.com/postman-cs/postman-repo-sync-action/actions/workflows/ci.yml) [](https://github.com/postman-cs/postman-repo-sync-action/releases) [](https://www.npmjs.com/package/@postman-cs/onboarding-repo-sync) [](LICENSE)
|
|
4
|
+
|
|
5
|
+
Exports Postman [collections](https://learning.postman.com/docs/use/use-collections/collections-schemas/) and [environments](https://learning.postman.com/docs/use/send-requests/variables/managing-environments/) into your repository and wires CI, [mock servers](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/), and [monitors](https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/) around them.
|
|
6
|
+
|
|
7
|
+
Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman-api-onboarding-action); the composite action's README has the full action-picker table.
|
|
8
|
+
|
|
9
|
+
- [Usage](#usage)
|
|
10
|
+
- [Examples](#examples)
|
|
11
|
+
- [Inputs](#inputs) / [Outputs](#outputs)
|
|
12
|
+
- [How it works](#how-it-works)
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
```yaml
|
|
17
|
+
jobs:
|
|
18
|
+
repo-sync:
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
permissions:
|
|
21
|
+
contents: write
|
|
22
|
+
actions: write
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@v5
|
|
25
|
+
|
|
26
|
+
- id: postman-auth
|
|
27
|
+
uses: postman-cs/postman-resolve-service-token-action@v2
|
|
28
|
+
with:
|
|
29
|
+
postman-region: us
|
|
30
|
+
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
|
|
31
|
+
|
|
32
|
+
- uses: postman-cs/postman-repo-sync-action@v2
|
|
33
|
+
with:
|
|
34
|
+
project-name: core-payments
|
|
35
|
+
postman-region: us
|
|
36
|
+
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
|
|
37
|
+
postman-access-token: ${{ steps.postman-auth.outputs.token }}
|
|
38
|
+
team-id: ${{ steps.postman-auth.outputs.team-id }}
|
|
39
|
+
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`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`.
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
`postman-region` controls the Postman public API host and generated [Postman CLI login region](https://learning.postman.com/docs/postman-cli/postman-cli-auth/). Use `us` for `https://api.getpostman.com` and `eu` for `https://api.eu.postman.com` when the team uses [EU data residency](https://learning.postman.com/docs/administration/enterprise/about-eu-data-residency/).
|
|
47
|
+
|
|
48
|
+
## Examples
|
|
49
|
+
|
|
50
|
+
### Full sync with workspace assets
|
|
51
|
+
|
|
52
|
+
```yaml
|
|
53
|
+
- uses: postman-cs/postman-repo-sync-action@v2
|
|
54
|
+
with:
|
|
55
|
+
project-name: core-payments
|
|
56
|
+
workspace-id: ws-123
|
|
57
|
+
baseline-collection-id: col-baseline
|
|
58
|
+
smoke-collection-id: col-smoke
|
|
59
|
+
contract-collection-id: col-contract
|
|
60
|
+
postman-region: us
|
|
61
|
+
environments-json: '["prod","stage"]'
|
|
62
|
+
env-runtime-urls-json: '{"prod":"https://api.example.com","stage":"https://stage-api.example.com"}'
|
|
63
|
+
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
|
|
64
|
+
postman-access-token: ${{ steps.postman-auth.outputs.token }}
|
|
65
|
+
team-id: ${{ steps.postman-auth.outputs.team-id }}
|
|
66
|
+
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`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](https://learning.postman.com/docs/administration/service-accounts/) 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](docs/credentials.md).
|
|
70
|
+
|
|
71
|
+
### Disable CI workflow generation
|
|
72
|
+
|
|
73
|
+
For existing repositories that already own their CI workflow, disable workflow generation:
|
|
74
|
+
|
|
75
|
+
```yaml
|
|
76
|
+
with:
|
|
77
|
+
generate-ci-workflow: false
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Custom CI workflow path
|
|
81
|
+
|
|
82
|
+
Write the generated workflow somewhere other than `.github/workflows/ci.yml`:
|
|
83
|
+
|
|
84
|
+
```yaml
|
|
85
|
+
with:
|
|
86
|
+
ci-workflow-path: .github/workflows/postman-sync.yml
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Commit-only mode for protected branches
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
```yaml
|
|
94
|
+
with:
|
|
95
|
+
repo-write-mode: commit-only
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`repo-write-mode` options:
|
|
99
|
+
|
|
100
|
+
| Mode | Behavior |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| `commit-and-push` | Commit generated files and push them back to the current checked out ref. |
|
|
103
|
+
| `commit-only` | Commit generated files without pushing. |
|
|
104
|
+
| `none` | Write files in the workspace only. |
|
|
105
|
+
|
|
106
|
+
### Reuse an existing mock server and monitor
|
|
107
|
+
|
|
108
|
+
Pass `mock-url` or `monitor-id` to validate and reuse existing [mock servers](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/) or [monitors](https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/) instead of creating new ones:
|
|
109
|
+
|
|
110
|
+
```yaml
|
|
111
|
+
with:
|
|
112
|
+
mock-url: https://abc123.mock.pstmn.io
|
|
113
|
+
monitor-id: 1e2f3a4b-monitor-id
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
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.
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
Where that variable comes from depends on who is running the collection:
|
|
121
|
+
|
|
122
|
+
- **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.
|
|
123
|
+
- **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`.
|
|
124
|
+
- **A runner you wire yourself** reads `mock-auth-required` and passes the variable however that system handles secrets.
|
|
125
|
+
|
|
126
|
+
A request to a private mock with no key set logs a console warning naming the variable, so a `401` explains its own fix.
|
|
127
|
+
|
|
128
|
+
For manual collection validation against the resolved mock, opt in to a dedicated Postman environment:
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
with:
|
|
132
|
+
mock-environment-enabled: true
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
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.
|
|
136
|
+
|
|
137
|
+
### mTLS certificates for Postman CLI runs
|
|
138
|
+
|
|
139
|
+
The generated CI workflow can run [Postman CLI collection runs](https://learning.postman.com/docs/postman-cli/postman-cli-collections/) 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:
|
|
140
|
+
|
|
141
|
+
```yaml
|
|
142
|
+
with:
|
|
143
|
+
ssl-client-cert: ${{ secrets.POSTMAN_SSL_CLIENT_CERT_B64 }}
|
|
144
|
+
ssl-client-key: ${{ secrets.POSTMAN_SSL_CLIENT_KEY_B64 }}
|
|
145
|
+
ssl-client-passphrase: ${{ secrets.POSTMAN_SSL_CLIENT_PASSPHRASE }}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Inputs
|
|
149
|
+
|
|
150
|
+
<!-- inputs-table:start -->
|
|
151
|
+
| Name | Description | Required | Default |
|
|
152
|
+
| --- | --- | --- | --- |
|
|
153
|
+
| `generate-ci-workflow` | Whether to generate the CI workflow file | no | `true` |
|
|
154
|
+
| `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 | |
|
|
155
|
+
| `ci-runner-os` | Runner operating system for the generated CI workflow. Use windows for native PowerShell Azure DevOps CI. | no | `linux` |
|
|
156
|
+
| `project-name` | Service project name used for environment, mock, and monitor naming. | yes | |
|
|
157
|
+
| `workspace-id` | Postman workspace ID used for workspace-link and export metadata. | no | |
|
|
158
|
+
| `baseline-collection-id` | Baseline collection ID used for exported artifacts and mock server creation. | no | |
|
|
159
|
+
| `monitor-type` | Type of monitor to create ("cloud" or "cli"). "cli" will skip cloud monitor creation and rely on the CI workflow. | no | `cloud` |
|
|
160
|
+
| `smoke-collection-id` | Smoke collection ID used for monitor creation. | no | |
|
|
161
|
+
| `contract-collection-id` | Contract collection ID used for exported artifacts. | no | |
|
|
162
|
+
| `onboarding-scope` | Onboarding scope. Use full for the complete pipeline or spec-only for repository linking and workspace/spec state only. | no | `full` |
|
|
163
|
+
| `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 cloud export. | no | `""` |
|
|
164
|
+
| `collection-sync-mode` | Collection sync lifecycle mode (refresh or version). | no | `refresh` |
|
|
165
|
+
| `spec-sync-mode` | Spec sync lifecycle mode (update or version). | no | `update` |
|
|
166
|
+
| `release-label` | Optional release label used for versioned naming. | no | |
|
|
167
|
+
| `monitor-id` | Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one. | no | |
|
|
168
|
+
| `mock-url` | Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one. | no | |
|
|
169
|
+
| `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` |
|
|
170
|
+
| `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` |
|
|
171
|
+
| `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 | `""` |
|
|
172
|
+
| `environments-json` | JSON array of environment slugs to create or update. | no | `["prod"]` |
|
|
173
|
+
| `git-provider` | Git provider override ('github', 'gitlab', 'bitbucket', 'azure-devops'). Auto-detected from environment when omitted. | no | |
|
|
174
|
+
| `ado-token` | Azure DevOps personal access token or system token used to push commits in Azure Pipelines. Defaults to SYSTEM_ACCESSTOKEN when available. | no | |
|
|
175
|
+
| `repo-url` | Explicit repository URL (GitHub, GitLab, or Azure DevOps). Defaults to the URL inferred from runner environment when omitted. | no | |
|
|
176
|
+
| `workspace-link-enabled` | Enable workspace linking. | no | `true` |
|
|
177
|
+
| `environment-sync-enabled` | Enable association of Postman environments to system environments. | no | `true` |
|
|
178
|
+
| `system-env-map-json` | JSON map of environment slug to system environment id. | no | `{}` |
|
|
179
|
+
| `environment-uids-json` | JSON map of environment slug to Postman environment uid. | no | `{}` |
|
|
180
|
+
| `env-runtime-urls-json` | JSON map of environment slug to runtime base URL. | no | `{}` |
|
|
181
|
+
| `artifact-dir` | Root directory for exported Postman artifacts. | no | `postman` |
|
|
182
|
+
| `repo-write-mode` | Repo mutation mode for generated artifacts and workflow files. | no | `commit-and-push` |
|
|
183
|
+
| `current-ref` | Explicit ref override for push-changes when the checkout is detached. | no | |
|
|
184
|
+
| `committer-name` | Git committer name for sync commits. | no | `Postman` |
|
|
185
|
+
| `committer-email` | Git committer email for sync commits. | no | `support@postman.com` |
|
|
186
|
+
| `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 | |
|
|
187
|
+
| `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 | |
|
|
188
|
+
| `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 | `""` |
|
|
189
|
+
| `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` |
|
|
190
|
+
| `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` |
|
|
191
|
+
| `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` |
|
|
192
|
+
| `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 | |
|
|
193
|
+
| `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 | |
|
|
194
|
+
| `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` |
|
|
195
|
+
| `github-token` | GitHub token used for repo variable persistence and commits. | no | |
|
|
196
|
+
| `gh-fallback-token` | Fallback token for repository variable APIs and workflow-file pushes. | no | |
|
|
197
|
+
| `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` |
|
|
198
|
+
| `ci-workflow-base64` | Optional base64-encoded ci.yml content. Defaults to the built-in template. | no | |
|
|
199
|
+
| `ssl-client-cert` | Base64-encoded PEM client certificate for Postman CLI mTLS runs. | no | |
|
|
200
|
+
| `ssl-client-key` | Base64-encoded PEM client private key for Postman CLI mTLS runs. | no | |
|
|
201
|
+
| `ssl-client-passphrase` | Optional passphrase for encrypted ssl-client-key. | no | |
|
|
202
|
+
| `ssl-extra-ca-certs` | Optional base64-encoded PEM CA certificate bundle for custom trust. | no | |
|
|
203
|
+
| `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 | |
|
|
204
|
+
| `spec-content-changed` | Whether bootstrap changed canonical spec content. Native Spec Hub tag publication is skipped on no-op syncs. | no | `true` |
|
|
205
|
+
| `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 | |
|
|
206
|
+
| `postman-region` | Postman data residency region for public API and Postman CLI calls. One of: us or eu. | no | `us` |
|
|
207
|
+
<!-- inputs-table:end -->
|
|
208
|
+
|
|
209
|
+
## Outputs
|
|
210
|
+
|
|
211
|
+
<!-- outputs-table:start -->
|
|
212
|
+
| Name | Description |
|
|
213
|
+
| --- | --- |
|
|
214
|
+
| `resolved-current-ref` | Resolved push target based on current-ref semantics. |
|
|
215
|
+
| `workspace-link-status` | Whether workspace linking succeeded, was skipped, or failed. |
|
|
216
|
+
| `environment-sync-status` | Whether environment sync succeeded, was skipped, or failed. |
|
|
217
|
+
| `environment-uids-json` | JSON map of environment slug to Postman environment uid. |
|
|
218
|
+
| `mock-url` | Created or reused mock server URL. |
|
|
219
|
+
| `mock-visibility` | Authoritatively observed mock visibility: public or private. |
|
|
220
|
+
| `mock-auth-required` | Whether the collection runner must supply postmanPrivateMockApiKey at runtime. |
|
|
221
|
+
| `mock-environment-uid` | Dedicated manual-validation environment UID when mock-environment-enabled succeeds. |
|
|
222
|
+
| `mock-environment-status` | Whether the optional manual-validation mock environment succeeded, was skipped, or failed. |
|
|
223
|
+
| `monitor-id` | Created or reused smoke monitor ID. |
|
|
224
|
+
| `repo-sync-summary-json` | JSON summary of repo materialization and workspace sync outputs. |
|
|
225
|
+
| `commit-sha` | Commit SHA produced by repo-write-mode, if any. |
|
|
226
|
+
| `sync-status` | Branch-aware sync status: synced, skipped-branch-gate, or empty under branch-strategy legacy. |
|
|
227
|
+
| `branch-decision` | Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION). |
|
|
228
|
+
| `spec-version-tag` | Native Spec Hub version tag created after successful canonical repo-sync finalization. |
|
|
229
|
+
| `spec-version-url` | Read-only URL for the tagged Spec Hub snapshot. |
|
|
230
|
+
<!-- outputs-table:end -->
|
|
231
|
+
|
|
232
|
+
## Self-contained binary (no npm / no Node)
|
|
233
|
+
|
|
234
|
+
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.
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
VERSION=2.1.10 # example: use a release that carries the binary
|
|
238
|
+
ASSET="postman-repo-sync-${VERSION}-linux-x64"
|
|
239
|
+
BASE_URL="https://github.com/postman-cs/postman-repo-sync-action/releases/download/v${VERSION}"
|
|
240
|
+
curl -fsSLO "${BASE_URL}/${ASSET}"
|
|
241
|
+
curl -fsSLO "${BASE_URL}/${ASSET}.sha256"
|
|
242
|
+
shasum -a 256 -c "${ASSET}.sha256"
|
|
243
|
+
chmod +x "$ASSET"
|
|
244
|
+
mv "$ASSET" postman-repo-sync
|
|
245
|
+
|
|
246
|
+
export POSTMAN_ACCESS_TOKEN="<minted-token>"
|
|
247
|
+
./postman-repo-sync --project-name core-payments --workspace-id ws-123 --repo-write-mode commit-only --result-json postman-repo-sync-result.json
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
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](docs/self-contained-binary.md).
|
|
251
|
+
|
|
252
|
+
## How it works
|
|
253
|
+
|
|
254
|
+
The action syncs a Postman workspace into the checked-out repository and can connect the workspace back to that repository:
|
|
255
|
+
|
|
256
|
+
- [Postman Collection v3](https://learning.postman.com/docs/use/use-collections/collections-schemas/) multi-file YAML exports under `postman/collections/`.
|
|
257
|
+
- [Postman environment](https://learning.postman.com/docs/use/send-requests/variables/managing-environments/) exports under `postman/environments/`.
|
|
258
|
+
- `.postman/resources.yaml` with local-to-cloud resource mappings.
|
|
259
|
+
- Optional `.postman/workflows.yaml` spec-to-collection metadata.
|
|
260
|
+
- Optional generated GitHub Actions workflow for [Postman CLI](https://learning.postman.com/docs/postman-cli/postman-cli-run-collection/) smoke and contract runs.
|
|
261
|
+
- Optional mock server, cloud monitor, workspace repository link, and system environment associations.
|
|
262
|
+
|
|
263
|
+
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.
|
|
264
|
+
|
|
265
|
+
A typical export looks like:
|
|
266
|
+
|
|
267
|
+
```text
|
|
268
|
+
postman/collections/core-payments/
|
|
269
|
+
collection.yaml
|
|
270
|
+
<folder>.yaml
|
|
271
|
+
<request>.yaml
|
|
272
|
+
postman/collections/[Smoke] core-payments/
|
|
273
|
+
collection.yaml
|
|
274
|
+
<folder>.yaml
|
|
275
|
+
<request>.yaml
|
|
276
|
+
postman/environments/
|
|
277
|
+
prod.postman_environment.json
|
|
278
|
+
.postman/
|
|
279
|
+
resources.yaml
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
```mermaid
|
|
283
|
+
flowchart LR
|
|
284
|
+
subgraph SYNC["repo-sync: once per onboarding run"]
|
|
285
|
+
W["Postman workspace"] -->|"gateway v3 export"| ART["postman/ + .postman/<br/>committed artifacts"]
|
|
286
|
+
ART --> WF["generated CI workflow"]
|
|
287
|
+
W --> MM["mock server +<br/>smoke monitor"]
|
|
288
|
+
end
|
|
289
|
+
subgraph LOOP["customer CI: every push / PR / 6h schedule"]
|
|
290
|
+
WF --> RUN["postman collection run<br/>Smoke then Contract"]
|
|
291
|
+
RES[".postman/resources.yaml<br/>collection UIDs + environment"] --> RUN
|
|
292
|
+
RUN --> API["live API or mock<br/>environment baseUrl"]
|
|
293
|
+
API --> REP["pass/fail per assertion<br/>+ --report-events to<br/>Postman run history"]
|
|
294
|
+
end
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
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](https://github.com/postman-cs/postman-bootstrap-action/blob/main/docs/contract-enforcement-layers.md) for the full two-layer model.
|
|
298
|
+
|
|
299
|
+
### What the generated CI workflow runs
|
|
300
|
+
|
|
301
|
+
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:
|
|
302
|
+
|
|
303
|
+
1. Checks out the repository and installs the Postman CLI from the region-appropriate install URL.
|
|
304
|
+
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).
|
|
305
|
+
3. Resolves the `[Smoke]` and `[Contract]` collection UIDs and the environment UID from the committed `.postman/resources.yaml`, failing fast if any are missing.
|
|
306
|
+
4. Decodes optional mTLS client certificates from the `POSTMAN_SSL_*` secrets and passes them to the runs.
|
|
307
|
+
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.
|
|
308
|
+
|
|
309
|
+
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](https://github.com/postman-cs/postman-bootstrap-action/blob/main/docs/generated-assertions.md), and the curated Smoke journey scripts are in [postman-smoke-flow-action's Generated Test Scripts](https://github.com/postman-cs/postman-smoke-flow-action/blob/main/docs/generated-tests.md).
|
|
310
|
+
|
|
311
|
+
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.
|
|
312
|
+
|
|
313
|
+
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.
|
|
314
|
+
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
Deeper reference:
|
|
318
|
+
|
|
319
|
+
- [Artifact layout and Collection v3 format](docs/artifact-layout.md), including sync modes and versioned releases.
|
|
320
|
+
- [Credentials](docs/credentials.md): `postman-api-key`, `postman-access-token`, credential preflight, GitHub tokens.
|
|
321
|
+
- [CLI usage](docs/cli.md): the `postman-repo-sync` binary for GitLab CI, Bitbucket Pipelines, and Azure DevOps.
|
|
322
|
+
- [Self-contained binary](docs/self-contained-binary.md): the no-npm/no-Node release binary for locked-down agents — install, credential minting, host allowlist, and a Jenkins pipeline.
|
|
323
|
+
- [Security](SECURITY.md): supported releases, reporting, and secret-handling expectations.
|
|
324
|
+
- [Support](SUPPORT.md): where to ask usage questions and what diagnostics to include.
|
|
325
|
+
- [Release policy](RELEASE_POLICY.md): immutable version tags and the rolling-major `vN` alias.
|
|
326
|
+
|
|
327
|
+
## Resources
|
|
328
|
+
|
|
329
|
+
- npm package: [@postman-cs/onboarding-repo-sync](https://www.npmjs.com/package/@postman-cs/onboarding-repo-sync)
|
|
330
|
+
- Postman API and auth references: [Postman API](https://learning.postman.com/docs/reference/postman-api/intro-api/), [API authentication](https://learning.postman.com/docs/reference/postman-api/authentication/), [Postman CLI auth](https://learning.postman.com/docs/postman-cli/postman-cli-auth/), [EU data residency](https://learning.postman.com/docs/administration/enterprise/about-eu-data-residency/)
|
|
331
|
+
- Postman artifact and runtime references: [Collection v3 schema](https://learning.postman.com/docs/use/use-collections/collections-schemas/), [Postman CLI collection runs](https://learning.postman.com/docs/postman-cli/postman-cli-run-collection/), [environments](https://learning.postman.com/docs/use/send-requests/variables/managing-environments/), [mock servers](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/), [monitors](https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/)
|
|
332
|
+
|
|
333
|
+
## Telemetry
|
|
334
|
+
|
|
335
|
+
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`.
|
|
336
|
+
|
|
337
|
+
## License
|
|
338
|
+
|
|
339
|
+
[MIT](LICENSE)
|
package/action.yml
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
name: 'Postman Onboarding: Repo Sync'
|
|
2
|
+
description: Export Postman collections and environments into your repo with CI wiring. Part of the Postman API Onboarding suite.
|
|
3
|
+
author: Postman
|
|
4
|
+
branding:
|
|
5
|
+
icon: refresh-cw
|
|
6
|
+
color: orange
|
|
7
|
+
inputs:
|
|
8
|
+
|
|
9
|
+
generate-ci-workflow:
|
|
10
|
+
description: Whether to generate the CI workflow file
|
|
11
|
+
required: false
|
|
12
|
+
default: "true"
|
|
13
|
+
ci-workflow-path:
|
|
14
|
+
description: Path to write the generated CI workflow file. Defaults to azure-pipelines.yml for Azure DevOps, .github/workflows/ci.yml otherwise.
|
|
15
|
+
required: false
|
|
16
|
+
ci-runner-os:
|
|
17
|
+
description: Runner operating system for the generated CI workflow. Use windows for native PowerShell Azure DevOps CI.
|
|
18
|
+
required: false
|
|
19
|
+
default: linux
|
|
20
|
+
project-name:
|
|
21
|
+
description: Service project name used for environment, mock, and monitor naming.
|
|
22
|
+
required: true
|
|
23
|
+
workspace-id:
|
|
24
|
+
description: Postman workspace ID used for workspace-link and export metadata.
|
|
25
|
+
required: false
|
|
26
|
+
baseline-collection-id:
|
|
27
|
+
description: Baseline collection ID used for exported artifacts and mock server creation.
|
|
28
|
+
required: false
|
|
29
|
+
monitor-type:
|
|
30
|
+
description: Type of monitor to create ("cloud" or "cli"). "cli" will skip cloud monitor creation and rely on the CI workflow.
|
|
31
|
+
required: false
|
|
32
|
+
default: cloud
|
|
33
|
+
smoke-collection-id:
|
|
34
|
+
description: Smoke collection ID used for monitor creation.
|
|
35
|
+
required: false
|
|
36
|
+
contract-collection-id:
|
|
37
|
+
description: Contract collection ID used for exported artifacts.
|
|
38
|
+
required: false
|
|
39
|
+
onboarding-scope:
|
|
40
|
+
description: Onboarding scope. Use full for the complete pipeline or spec-only for repository linking and workspace/spec state only.
|
|
41
|
+
required: false
|
|
42
|
+
default: full
|
|
43
|
+
prebuilt-collections-json:
|
|
44
|
+
description: 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 cloud export.
|
|
45
|
+
required: false
|
|
46
|
+
default: ''
|
|
47
|
+
collection-sync-mode:
|
|
48
|
+
description: Collection sync lifecycle mode (refresh or version).
|
|
49
|
+
required: false
|
|
50
|
+
default: refresh
|
|
51
|
+
spec-sync-mode:
|
|
52
|
+
description: Spec sync lifecycle mode (update or version).
|
|
53
|
+
required: false
|
|
54
|
+
default: update
|
|
55
|
+
release-label:
|
|
56
|
+
description: Optional release label used for versioned naming.
|
|
57
|
+
required: false
|
|
58
|
+
monitor-id:
|
|
59
|
+
description: Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one.
|
|
60
|
+
required: false
|
|
61
|
+
mock-url:
|
|
62
|
+
description: Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.
|
|
63
|
+
required: false
|
|
64
|
+
mock-visibility:
|
|
65
|
+
description: 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.
|
|
66
|
+
required: false
|
|
67
|
+
default: private
|
|
68
|
+
mock-environment-enabled:
|
|
69
|
+
description: 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.
|
|
70
|
+
required: false
|
|
71
|
+
default: "false"
|
|
72
|
+
monitor-cron:
|
|
73
|
+
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).
|
|
74
|
+
required: false
|
|
75
|
+
default: ""
|
|
76
|
+
environments-json:
|
|
77
|
+
description: JSON array of environment slugs to create or update.
|
|
78
|
+
required: false
|
|
79
|
+
default: '["prod"]'
|
|
80
|
+
git-provider:
|
|
81
|
+
description: Git provider override ('github', 'gitlab', 'bitbucket', 'azure-devops'). Auto-detected from environment when omitted.
|
|
82
|
+
required: false
|
|
83
|
+
ado-token:
|
|
84
|
+
description: Azure DevOps personal access token or system token used to push commits in Azure Pipelines. Defaults to SYSTEM_ACCESSTOKEN when available.
|
|
85
|
+
required: false
|
|
86
|
+
repo-url:
|
|
87
|
+
description: 'Explicit repository URL (GitHub, GitLab, or Azure DevOps). Defaults to the URL inferred from runner environment when omitted.'
|
|
88
|
+
required: false
|
|
89
|
+
integration-backend:
|
|
90
|
+
description: Advanced/internal. Integration backend for managed workspace linking and environment sync; leave unset to use the default.
|
|
91
|
+
required: false
|
|
92
|
+
workspace-link-enabled:
|
|
93
|
+
description: Enable workspace linking.
|
|
94
|
+
required: false
|
|
95
|
+
default: 'true'
|
|
96
|
+
environment-sync-enabled:
|
|
97
|
+
description: Enable association of Postman environments to system environments.
|
|
98
|
+
required: false
|
|
99
|
+
default: 'true'
|
|
100
|
+
system-env-map-json:
|
|
101
|
+
description: JSON map of environment slug to system environment id.
|
|
102
|
+
required: false
|
|
103
|
+
default: '{}'
|
|
104
|
+
environment-uids-json:
|
|
105
|
+
description: JSON map of environment slug to Postman environment uid.
|
|
106
|
+
required: false
|
|
107
|
+
default: '{}'
|
|
108
|
+
env-runtime-urls-json:
|
|
109
|
+
description: JSON map of environment slug to runtime base URL.
|
|
110
|
+
required: false
|
|
111
|
+
default: '{}'
|
|
112
|
+
artifact-dir:
|
|
113
|
+
description: Root directory for exported Postman artifacts.
|
|
114
|
+
required: false
|
|
115
|
+
default: postman
|
|
116
|
+
repo-write-mode:
|
|
117
|
+
description: Repo mutation mode for generated artifacts and workflow files.
|
|
118
|
+
required: false
|
|
119
|
+
default: commit-and-push
|
|
120
|
+
current-ref:
|
|
121
|
+
description: Explicit ref override for push-changes when the checkout is detached.
|
|
122
|
+
required: false
|
|
123
|
+
committer-name:
|
|
124
|
+
description: Git committer name for sync commits.
|
|
125
|
+
required: false
|
|
126
|
+
default: Postman
|
|
127
|
+
committer-email:
|
|
128
|
+
description: Git committer email for sync commits.
|
|
129
|
+
required: false
|
|
130
|
+
default: support@postman.com
|
|
131
|
+
postman-api-key:
|
|
132
|
+
description: 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.
|
|
133
|
+
required: false
|
|
134
|
+
postman-access-token:
|
|
135
|
+
description: 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.
|
|
136
|
+
required: false
|
|
137
|
+
team-id:
|
|
138
|
+
description: 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.
|
|
139
|
+
required: false
|
|
140
|
+
default: ""
|
|
141
|
+
secrets-resolver:
|
|
142
|
+
description: '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.'
|
|
143
|
+
required: false
|
|
144
|
+
default: "none"
|
|
145
|
+
credential-preflight:
|
|
146
|
+
description: '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.'
|
|
147
|
+
required: false
|
|
148
|
+
default: warn
|
|
149
|
+
branch-strategy:
|
|
150
|
+
description: "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."
|
|
151
|
+
required: false
|
|
152
|
+
default: legacy
|
|
153
|
+
canonical-branch:
|
|
154
|
+
description: 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.
|
|
155
|
+
required: false
|
|
156
|
+
channels:
|
|
157
|
+
description: 'Comma-separated channel map for long-lived promotion branches, e.g. "develop=DEV, staging=STAGE, release/*=RC". Channel branches maintain prefix-named parallel asset sets and never mutate canonical assets.'
|
|
158
|
+
required: false
|
|
159
|
+
preview-ttl:
|
|
160
|
+
description: 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).
|
|
161
|
+
required: false
|
|
162
|
+
default: '30'
|
|
163
|
+
github-token:
|
|
164
|
+
description: GitHub token used for repo variable persistence and commits.
|
|
165
|
+
required: false
|
|
166
|
+
gh-fallback-token:
|
|
167
|
+
description: Fallback token for repository variable APIs and workflow-file pushes.
|
|
168
|
+
required: false
|
|
169
|
+
org-mode:
|
|
170
|
+
description: 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.
|
|
171
|
+
required: false
|
|
172
|
+
default: 'false'
|
|
173
|
+
ci-workflow-base64:
|
|
174
|
+
description: Optional base64-encoded ci.yml content. Defaults to the built-in template.
|
|
175
|
+
required: false
|
|
176
|
+
ssl-client-cert:
|
|
177
|
+
description: Base64-encoded PEM client certificate for Postman CLI mTLS runs.
|
|
178
|
+
required: false
|
|
179
|
+
ssl-client-key:
|
|
180
|
+
description: Base64-encoded PEM client private key for Postman CLI mTLS runs.
|
|
181
|
+
required: false
|
|
182
|
+
ssl-client-passphrase:
|
|
183
|
+
description: Optional passphrase for encrypted ssl-client-key.
|
|
184
|
+
required: false
|
|
185
|
+
ssl-extra-ca-certs:
|
|
186
|
+
description: Optional base64-encoded PEM CA certificate bundle for custom trust.
|
|
187
|
+
required: false
|
|
188
|
+
spec-id:
|
|
189
|
+
description: 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.
|
|
190
|
+
required: false
|
|
191
|
+
spec-content-changed:
|
|
192
|
+
description: Whether bootstrap changed canonical spec content. Native Spec Hub tag publication is skipped on no-op syncs.
|
|
193
|
+
required: false
|
|
194
|
+
default: 'true'
|
|
195
|
+
spec-path:
|
|
196
|
+
description: 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.
|
|
197
|
+
required: false
|
|
198
|
+
postman-region:
|
|
199
|
+
description: "Postman data residency region for public API and Postman CLI calls. One of: us or eu."
|
|
200
|
+
required: false
|
|
201
|
+
default: us
|
|
202
|
+
postman-stack:
|
|
203
|
+
description: 'Postman stack profile. Leave at the default unless Postman support directs otherwise.'
|
|
204
|
+
required: false
|
|
205
|
+
default: prod
|
|
206
|
+
outputs:
|
|
207
|
+
integration-backend:
|
|
208
|
+
description: Resolved integration backend for the onboarding run.
|
|
209
|
+
resolved-current-ref:
|
|
210
|
+
description: Resolved push target based on current-ref semantics.
|
|
211
|
+
workspace-link-status:
|
|
212
|
+
description: Whether workspace linking succeeded, was skipped, or failed.
|
|
213
|
+
environment-sync-status:
|
|
214
|
+
description: Whether environment sync succeeded, was skipped, or failed.
|
|
215
|
+
environment-uids-json:
|
|
216
|
+
description: JSON map of environment slug to Postman environment uid.
|
|
217
|
+
mock-url:
|
|
218
|
+
description: Created or reused mock server URL.
|
|
219
|
+
mock-visibility:
|
|
220
|
+
description: "Authoritatively observed mock visibility: public or private."
|
|
221
|
+
mock-auth-required:
|
|
222
|
+
description: Whether the collection runner must supply postmanPrivateMockApiKey at runtime.
|
|
223
|
+
mock-environment-uid:
|
|
224
|
+
description: Dedicated manual-validation environment UID when mock-environment-enabled succeeds.
|
|
225
|
+
mock-environment-status:
|
|
226
|
+
description: Whether the optional manual-validation mock environment succeeded, was skipped, or failed.
|
|
227
|
+
monitor-id:
|
|
228
|
+
description: Created or reused smoke monitor ID.
|
|
229
|
+
repo-sync-summary-json:
|
|
230
|
+
description: JSON summary of repo materialization and workspace sync outputs.
|
|
231
|
+
commit-sha:
|
|
232
|
+
description: Commit SHA produced by repo-write-mode, if any.
|
|
233
|
+
sync-status:
|
|
234
|
+
description: "Branch-aware sync status: synced, skipped-branch-gate, or empty under branch-strategy legacy."
|
|
235
|
+
branch-decision:
|
|
236
|
+
description: Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION).
|
|
237
|
+
spec-version-tag:
|
|
238
|
+
description: Native Spec Hub version tag created after successful canonical repo-sync finalization.
|
|
239
|
+
spec-version-url:
|
|
240
|
+
description: Read-only URL for the tagged Spec Hub snapshot.
|
|
241
|
+
runs:
|
|
242
|
+
using: node24
|
|
243
|
+
main: dist/action.cjs
|