@postman-cs/onboarding-api 3.4.10 → 3.5.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 (3) hide show
  1. package/README.md +10 -2
  2. package/action.yml +16 -4
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -72,11 +72,18 @@ Use `postman-region: eu` for [EU data residency](https://learning.postman.com/do
72
72
  | Sync generated artifacts without the composite wrapper | [Postman Onboarding: Repo Sync](https://github.com/postman-cs/postman-repo-sync-action) | Lower-level artifact, environment, mock, monitor, and CI workflow sync. |
73
73
  | Link an existing workspace to Insights | [Postman Onboarding: Insights Linking](https://github.com/postman-cs/postman-insights-onboarding-action) | Lower-level Insights service-to-workspace binding. |
74
74
 
75
+ ## Monorepos
76
+
77
+ Use one dispatcher under the repository-root `.github/workflows/` directory; GitHub ignores workflow files inside service directories. Set `working-directory: services/<service>` on the composite so relative spec and flow paths, `postman/` exports, and `.postman/` state stay inside that service. Each service should use its own `project-name` and Postman workspace by default.
78
+
79
+ When `working-directory` is omitted, `generate-ci-workflow` still defaults to `true`. With a service directory it defaults to `false`, and explicitly requesting `true` fails because the nested workflow would not run. Start with [`examples/monorepo-dispatcher.yml`](examples/monorepo-dispatcher.yml), which detects changed services, serializes onboarding commits, prevents generated-artifact loops, and runs service collections in parallel. The canonical layout and CLI alternative are in the [repo-sync monorepo guide](https://github.com/postman-cs/postman-repo-sync-action/blob/main/docs/monorepo.md).
80
+
75
81
  ## Scenario guide
76
82
 
77
83
  - [Quick start](#quick-start): new GitHub API repository with service-token credential resolution.
78
84
  - [Governance and environments](#governance-and-environments): workspace ownership, governance groups, environments, and runtime URLs.
79
85
  - [Existing service refresh](#existing-service-refresh): reuse known Postman asset IDs while updating the spec and generated artifacts.
86
+ - [Monorepos](#monorepos): isolate service-local inputs and generated artifacts behind one root dispatcher.
80
87
  - [Protected branches](#protected-branch-repos-commit-only-plus-pr): create a sync commit for a pull request instead of pushing directly.
81
88
  - [Insights linking](#insights-linking): connect discovered services to the onboarded workspace.
82
89
  - [AWS spec discovery](#aws-spec-discovery): discover the spec first, then feed the result into this composite action.
@@ -178,7 +185,7 @@ The full pattern, including sync-branch creation and programmatic PR opening, is
178
185
 
179
186
  ### Insights linking
180
187
 
181
- When `enable-insights: true` and `onboarding-scope: full`, the action chains `postman-cs/postman-insights-onboarding-action@v2.4.4` after bootstrap and repo sync, using the workspace from bootstrap plus the first environment from `environments-json`. Spec-only onboarding skips Insights because that path intentionally does not create the required environment. This release accepts live human sessions identified by `user_type=human` even when `consumerType` is absent. Insights still requires a separate human-user PMAK and human-user session access token; do not pass the service-account credentials used by bootstrap and repo sync.
188
+ When `enable-insights: true` and `onboarding-scope: full`, the action chains `postman-cs/postman-insights-onboarding-action@v2.5.0` after bootstrap and repo sync, using the workspace from bootstrap plus the first environment from `environments-json`. Spec-only onboarding skips Insights because that path intentionally does not create the required environment. This release accepts live human sessions identified by `user_type=human` even when `consumerType` is absent. Insights still requires a separate human-user PMAK and human-user session access token; do not pass the service-account credentials used by bootstrap and repo sync.
182
189
 
183
190
  ```yaml
184
191
  - uses: actions/checkout@v5
@@ -249,6 +256,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
249
256
  <!-- inputs-table:start -->
250
257
  | Name | Description | Required | Default |
251
258
  | --- | --- | --- | --- |
259
+ | `working-directory` | Repository-root-relative service directory used for all local inputs and generated artifacts. | no | |
252
260
  | `workspace-id` | Existing Postman workspace ID. | no | |
253
261
  | `spec-id` | Existing Postman spec ID. | no | |
254
262
  | `baseline-collection-id` | Existing baseline collection ID. | no | |
@@ -264,7 +272,7 @@ The hook only attaches `x-api-key` for `*.mock.pstmn.io` hosts, so it stays iner
264
272
  | `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 | `public` |
265
273
  | `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` |
266
274
  | `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 | |
267
- | `generate-ci-workflow` | Whether to generate the CI workflow file. | no | `true` |
275
+ | `generate-ci-workflow` | Whether to generate the CI workflow file. Defaults to true at the repository root and false when working-directory is set. | no | |
268
276
  | `ci-workflow-path` | Path to write the generated CI workflow file. | no | `.github/workflows/ci.yml` |
269
277
  | `ci-runner-os` | Runner operating system for the generated CI workflow. Use windows for native PowerShell Azure DevOps CI. | no | `linux` |
270
278
  | `project-name` | Service project name used across bootstrap and repo sync phases. | yes | |
package/action.yml CHANGED
@@ -5,7 +5,10 @@ branding:
5
5
  icon: send
6
6
  color: orange
7
7
  inputs:
8
-
8
+ working-directory:
9
+ description: Repository-root-relative service directory used for all local inputs and generated artifacts.
10
+ required: false
11
+ default: ''
9
12
  workspace-id:
10
13
  description: Existing Postman workspace ID.
11
14
  required: false
@@ -59,9 +62,8 @@ inputs:
59
62
  required: false
60
63
  default: ""
61
64
  generate-ci-workflow:
62
- description: Whether to generate the CI workflow file.
65
+ description: Whether to generate the CI workflow file. Defaults to true at the repository root and false when working-directory is set.
63
66
  required: false
64
- default: "true"
65
67
  ci-workflow-path:
66
68
  description: Path to write the generated CI workflow file.
67
69
  required: false
@@ -455,6 +457,7 @@ runs:
455
457
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
456
458
  POSTMAN_REGION: ${{ inputs.postman-region }}
457
459
  POSTMAN_STACK: ${{ inputs.postman-stack }}
460
+ WORKING_DIRECTORY: ${{ inputs.working-directory }}
458
461
  CREDENTIAL_PREFLIGHT: ${{ inputs.credential-preflight }}
459
462
  REPO_WRITE_MODE: ${{ inputs.repo-write-mode }}
460
463
  POSTMAN_API_KEY: ${{ inputs.postman-api-key }}
@@ -465,6 +468,12 @@ runs:
465
468
  INSIGHTS_POSTMAN_API_KEY: ${{ inputs.insights-postman-api-key }}
466
469
  INSIGHTS_POSTMAN_ACCESS_TOKEN: ${{ inputs.insights-postman-access-token }}
467
470
  run: |
471
+ if [ -n "$WORKING_DIRECTORY" ]; then
472
+ if ! node -e 'const fs=require("node:fs"),path=require("node:path");const target=path.resolve(process.env.GITHUB_WORKSPACE,process.env.WORKING_DIRECTORY);process.exit(fs.existsSync(target)&&fs.statSync(target).isDirectory()?0:1)'; then
473
+ echo "::error::working-directory does not exist under GITHUB_WORKSPACE. Create the directory or correct the input."
474
+ exit 1
475
+ fi
476
+ fi
468
477
  case "$POSTMAN_STACK" in
469
478
  prod|beta) ;;
470
479
  *)
@@ -524,6 +533,7 @@ runs:
524
533
  # the pinned child metadata contract.
525
534
  INPUT_REPO_URL: ${{ inputs.repo-url }}
526
535
  with:
536
+ working-directory: ${{ inputs.working-directory }}
527
537
  project-name: ${{ inputs.project-name }}
528
538
  workspace-id: ${{ inputs.workspace-id }}
529
539
  spec-id: ${{ inputs.spec-id }}
@@ -577,6 +587,7 @@ runs:
577
587
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
578
588
  POSTMAN_BRANCH_DECISION: ${{ steps.branch_decision.outputs.branch-decision }}
579
589
  with:
590
+ working-directory: ${{ inputs.working-directory }}
580
591
  project-name: ${{ inputs.project-name }}
581
592
  workspace-id: ${{ steps.bootstrap.outputs.workspace-id }}
582
593
  spec-id: ${{ steps.bootstrap.outputs.spec-id }}
@@ -601,6 +612,7 @@ runs:
601
612
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
602
613
  POSTMAN_BRANCH_DECISION: ${{ steps.branch_decision.outputs.branch-decision }}
603
614
  with:
615
+ working-directory: ${{ inputs.working-directory }}
604
616
  project-name: ${{ inputs.project-name }}
605
617
  repo-url: ${{ inputs.repo-url }}
606
618
  workspace-id: ${{ steps.bootstrap.outputs.workspace-id }}
@@ -793,7 +805,7 @@ runs:
793
805
  - id: insights_onboarding
794
806
  if: inputs.onboarding-scope == 'full' && inputs.enable-insights == 'true' && steps.branch_decision.outputs.tier != 'gated'
795
807
  name: Onboard Postman Insights
796
- uses: postman-cs/postman-insights-onboarding-action@v2.4.4
808
+ uses: postman-cs/postman-insights-onboarding-action@v2.5.0
797
809
  env:
798
810
  POSTMAN_TEAM_ID: ${{ inputs.postman-team-id }}
799
811
  POSTMAN_BRANCH_DECISION: ${{ steps.branch_decision.outputs.branch-decision }}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@postman-cs/onboarding-api",
3
- "version": "3.4.10",
3
+ "version": "3.5.0",
4
4
  "description": "Composite Postman API onboarding GitHub Action.",
5
5
  "files": [
6
6
  "action.yml",