@postman-cse/onboarding-bootstrap 0.13.0 → 0.14.0

package/README.md

@@ -1,27 +1,28 @@
 # postman-bootstrap-action
 
-Public open-alpha GitHub Action for Postman workspace bootstrap from a registry-backed OpenAPI spec.
+Public customer preview GitHub Action for Postman workspace bootstrap from a registry-backed OpenAPI spec.
 
 ## Scope
 
 This action preserves the bootstrap slice of the API Catalog demo flow:
 
 - create or reuse a Postman workspace
-- assign the workspace to a governance group through the current Bifrost and internal path
+- assign the workspace to a configured governance group when a group name and `postman-access-token` are provided
 - invite the requester and add workspace admins
 - upload or update a remote spec in Spec Hub (after normalizing operation summaries — see below)
+- optionally check for OpenAPI breaking changes before any Postman mutations
 - lint the uploaded spec by UID with the Postman CLI
 - generate missing baseline, smoke, and contract collections or reuse existing ones
 - optionally refresh current collections from the latest spec or create release-scoped spec and collection assets
 - inject generated tests and apply collection tags
 - reuse committed `.postman/resources.yaml` state from the checked-out ref when present
 
-The public open-alpha contract uses kebab-case inputs and outputs and defaults `integration-backend` to `bifrost`.
+The public customer preview contract uses kebab-case inputs and outputs and defaults `integration-backend` to `bifrost`.
 
 ### Git provider support
 
 Workspace-to-repository linking via Bifrost supports both **GitHub** and **GitLab** (cloud and self-hosted) repository URLs. The `repo-url` value (or the auto-derived URL from CI environment variables) is stored as-is by Bifrost without provider-specific validation. URL normalization handles HTTPS, SSH (`git@`), and `.git` suffix variants for both providers.
-The public open-alpha contract uses kebab-case inputs and outputs and defaults `integration-backend` to `bifrost`.
+The public customer preview contract uses kebab-case inputs and outputs and defaults `integration-backend` to `bifrost`.
 
 For existing services, pass `workspace-id`, `spec-id`, and any existing collection IDs to rerun the bootstrap safely without creating duplicate Postman assets. When `.postman/resources.yaml` is present in the checked-out ref, the action also reuses its workspace/spec/collection mappings automatically.
 
@@ -87,6 +88,30 @@ postman-bootstrap --workspace-team-id 132319 ...
 Or via environment variable: `export POSTMAN_WORKSPACE_TEAM_ID=132319`
 
 Non-org accounts (single team) are unaffected and do not need this input.
+
+### Governance group assignment
+
+Governance assignment is optional and customer-configured:
+
+1. Set the repository custom property `postman-governance-group` to the Postman governance group name.
+2. Set `postman-access-token` so the action can perform workspace enrichment after the workspace exists.
+
+Example:
+
+```yaml
+with:
+  github-token: ${{ github.token }}
+  postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+```
+
+For one-off runs, `governance-group` can be passed directly and overrides the
+repository custom property. `governance-mapping-json` remains supported as a
+domain-map fallback for older workflows.
+
+If the group configuration is missing, the group is not found, or the access token is
+expired, bootstrap logs a warning and continues with the created workspace,
+spec, and collections.
+
 ### OpenAPI operation summaries (normalization)
 
 Before upload to Spec Hub, the action parses JSON or YAML OpenAPI documents and adjusts **path operations** so collection generation is less likely to fail:
@@ -100,6 +125,54 @@ This runs in `src/index.ts` before upload. If nothing under `paths` needs changi
 
 The root `spec-url` must be HTTPS and is fetched with pinned DNS resolution. The action blocks credential-bearing URLs, localhost/private/link-local/internal destinations, unsafe redirects, DNS rebinding attempts, and oversized OpenAPI resources before uploading content to Spec Hub. Root fetches are capped at 25 MiB, and fetch errors redact URL credentials, query strings, and fragments before logging.
 
+### Loading the spec from the workspace (`spec-path`)
+
+For Git-first workflows the spec is usually checked into the same repo that runs the action, so an HTTPS URL is redundant (or impossible without making the repo public). Pass `spec-path` instead of `spec-url` to read the document directly from the checked-out workspace:
+
+```yaml
+- uses: actions/checkout@v5
+- uses: postman-cs/postman-bootstrap-action@v0
+  with:
+    project-name: core-payments
+    spec-path: apis/core-payments/openapi.yaml
+    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+```
+
+Only one of `spec-url` or `spec-path` may be set. When `spec-path` is used the action reads the file from disk, skips the URL-safety machinery, and still resolves any external HTTPS `$ref`s through the same hardened fetcher. Local-file `$ref`s are not followed.
+
+### OpenAPI breaking-change check
+
+Breaking-change detection is disabled by default. Enable it with `breaking-change-mode` when you want bootstrap to compare the incoming OpenAPI contract before creating or updating Postman resources.
+
+Modes:
+
+- `off`: default. No comparison runs and `openapi-changes` is not installed.
+- `previous-spec`: compares the incoming Spec Hub upload content with the existing `spec-id` content. If there is no previous spec, the check is marked `skipped`.
+- `pr-native`: compares `breaking-target-ref` or the detected PR target branch version of `spec-path` against the checked-out working tree. If no target-branch spec is available, it falls back to `breaking-baseline-spec-path` when configured.
+- `baseline-only`: compares `breaking-baseline-spec-path` against the incoming spec. If the baseline file is missing, the check is marked `skipped`.
+
+The action installs a pinned `pb33f/openapi-changes` release into the runner temp directory, verifies the archive checksum, validates archive paths before extraction, and runs the binary by absolute path. It does not require customers to preinstall the tool, and it does not use `npx`, global npm installs, or `curl | sh`.
+
+Summary and log files default to `$RUNNER_TEMP/postman-bootstrap/`, so they are runner files, not committed repo changes. The markdown summary is also appended to the GitHub job summary when `$GITHUB_STEP_SUMMARY` is available. Pass `breaking-summary-path` or `breaking-log-path` only if your workflow wants explicit file locations for later `actions/upload-artifact` steps.
+
+Example:
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0
+- uses: postman-cs/postman-bootstrap-action@v0
+  with:
+    project-name: core-payments
+    spec-path: apis/core-payments/openapi.yaml
+    breaking-change-mode: pr-native
+    breaking-target-ref: ${{ github.base_ref }}
+    breaking-baseline-spec-path: apis/core-payments/openapi.baseline.yaml
+    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+```
+
+If breaking changes are detected, bootstrap fails before workspace, spec, or collection mutation. Missing comparison sources are reported as `skipped` and do not fail the run.
+
 ## Usage
 
 ```yaml
@@ -110,7 +183,7 @@ jobs:
       actions: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: postman-cs/postman-bootstrap-action@v0
         with:
           project-name: core-payments
@@ -119,14 +192,14 @@ jobs:
           requester-email: owner@example.com
           workspace-admin-user-ids: 101,102
           spec-url: https://example.com/openapi.yaml
-          governance-mapping-json: '{"core-banking":"Core Banking"}'
+          github-token: ${{ github.token }}
           postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
           postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
 
   bootstrap-existing:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: postman-cs/postman-bootstrap-action@v0
         with:
           project-name: core-payments
@@ -190,6 +263,7 @@ Rollback behavior:
 | `CONTRACT_REF_DEPTH_EXCEEDED` | Ref nesting exceeded the configured limit. | Flatten recursive/deep ref chains. |
 | `CONTRACT_REF_SIZE_EXCEEDED` | A fetched resource or total fetched bytes exceeded limits. | Reduce spec/ref size or pre-bundle the document. |
 | `CONTRACT_SPEC_PARSE_FAILED` | The fetched document was not valid JSON/YAML object content. | Fix the source document syntax. |
+| `CONTRACT_SPEC_READ_FAILED` | The `spec-path` file could not be read from the workspace. | Verify the file exists at the configured path and that the workflow checked out the branch that contains it. |
 | `CONTRACT_SPEC_VALIDATION_FAILED` | The bundled document failed OpenAPI validation. | Fix OpenAPI validation errors. |
 | `CONTRACT_UNSUPPORTED_OPENAPI_VERSION` | The document was not OpenAPI 3.0 or 3.1. | Provide an OpenAPI 3.0/3.1 document. |
 | `CONTRACT_NO_ELIGIBLE_OPERATIONS` | No eligible `paths` operations with responses were found. | Add path operations with responses. |
@@ -298,16 +372,26 @@ steps:
 | `spec-sync-mode` | `update` | Spec lifecycle policy. `update` keeps one canonical spec current in Spec Hub, while `version` creates or reuses a release-scoped spec asset. |
 | `release-label` | | Optional release label used for versioned specs and collections. When omitted for versioned sync, the action derives one from GitHub tag or branch metadata. |
 | `project-name` | | Service name used in workspace and asset naming. |
-| `domain` | | Business domain used for governance assignment. |
+| `domain` | | Business domain metadata. Also used by the legacy `governance-mapping-json` fallback. |
 | `domain-code` | | Short prefix used when constructing the workspace name. |
 | `requester-email` | | Optional user invited into the workspace. |
 | `workspace-admin-user-ids` | | Comma-separated Postman user IDs to grant admin access. |
 | `workspace-team-id` | | Numeric sub-team ID for org-mode workspace creation. Required when the API key belongs to an org with multiple sub-teams. |
-| `spec-url` | | Required registry-backed OpenAPI document URL. |
-| `governance-mapping-json` | `{}` | Map of domain to governance group name. |
+| `spec-url` | | HTTPS URL to the OpenAPI document. Provide either `spec-url` or `spec-path`. |
+| `spec-path` | | Local filesystem path to the OpenAPI document, relative to the checked-out workspace (e.g. `apis/identity/openapi.yaml`). Use this when the spec lives in the repo and you don't want to host it over HTTPS. Provide either `spec-url` or `spec-path`. |
+| `breaking-change-mode` | `off` | OpenAPI breaking-change comparison mode: `off`, `pr-native`, `baseline-only`, or `previous-spec`. |
+| `breaking-baseline-spec-path` | | Workspace-relative baseline OpenAPI spec path used by `baseline-only` and as `pr-native` fallback. |
+| `breaking-rules-path` | `changes-rules.yaml` | Workspace-relative `openapi-changes` rules file. Missing files are ignored. |
+| `breaking-target-ref` | | Optional target branch or git ref override for `pr-native`. |
+| `breaking-summary-path` | | Optional markdown report output path. Defaults to a runner-temp file. |
+| `breaking-log-path` | | Optional raw command log output path. Defaults to a runner-temp file. |
+| `governance-group` | | Postman governance group name. Overrides the `postman-governance-group` repository custom property and legacy domain mapping. |
+| `governance-mapping-json` | `{}` | Legacy fallback map of `domain` value to Postman governance group name. Prefer the repository custom property or `governance-group`. |
+| `github-token` | | GitHub token used to read the `postman-governance-group` repository custom property. |
+| `gh-fallback-token` | | Fallback GitHub token used to read repository custom properties when `github-token` cannot. |
 | `postman-api-key` | | Required for all Postman asset operations. |
-| `postman-access-token` | | Required for governance assignment and canonical workspace validation during reruns. |
-| `integration-backend` | `bifrost` | Current public open-alpha backend. |
+| `postman-access-token` | | Required for governance assignment, cloud spec-to-collection syncing, and canonical workspace validation during reruns. |
+| `integration-backend` | `bifrost` | Current public customer preview backend. |
 
 ## Lifecycle Modes
 
@@ -406,11 +490,11 @@ The `postman-api-key` is a Postman API key (PMAK) used for all standard Postman
 
 > **Note:** The PMAK is a long-lived key tied to your Postman account. It does not require periodic renewal like the `postman-access-token`.
 
-### Obtaining `postman-access-token` (Open Alpha)
+### Obtaining `postman-access-token` (Customer Preview)
 
-> **⚠️ 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.
+> **⚠️ Customer Preview limitation:** The `postman-access-token` input requires a manually-extracted session token. There is currently no public API to exchange a Postman API key (PMAK) for an access token programmatically. This manual step will be eliminated before GA.
 
-The `postman-access-token` is a Postman session token (`x-access-token`) required for internal API operations that the standard PMAK API key cannot perform — specifically governance group assignment and canonical workspace validation during reruns in this action. Without it, those steps degrade to warning-based behavior and name-based workspace fallback during provisioning.
+The `postman-access-token` is a Postman session token required for workspace enrichment operations that the standard PMAK API key cannot perform, including governance group assignment, cloud spec-to-collection syncing, and canonical workspace validation during reruns. Without it, those steps degrade to warning-based behavior and name-based workspace fallback during provisioning.
 
 **To obtain and configure the token:**
 
@@ -450,6 +534,8 @@ The `postman-access-token` is a Postman session token (`x-access-token`) require
 - `contract-collection-id`
 - `collections-json`
 - `lint-summary-json`
+- `breaking-change-status`
+- `breaking-change-summary-json`
 
 ## Local development
 
@@ -462,11 +548,11 @@ npm run build
 
 `npm run build` produces the committed `dist/index.cjs` action bundle used by `action.yml`.
 
-## Open-Alpha Release Strategy
+## Customer Preview Release Strategy
 
-- Open-alpha channel tags use `v0.x.y`.
+- Customer Preview channel tags use `v0.x.y`.
 - Consumers can pin immutable tags such as `v0.2.0` for reproducibility.
-- Moving tag `v0` is used only as the rolling open-alpha channel.
+- Moving tag `v0` is used only as the rolling customer preview channel.
 
 ## REST Migration Seam
 

package/action.yml

@@ -1,5 +1,5 @@
 name: postman-bootstrap-action
-description: Public open-alpha action contract for Postman workspace, spec, and collection bootstrap.
+description: Public customer preview action contract for Postman workspace, spec, and collection bootstrap.
 inputs:
 
   workspace-id:
@@ -41,6 +41,9 @@ inputs:
   domain-code:
     description: Workspace naming prefix
     required: false
+  governance-group:
+    description: Postman governance workspace group name. Overrides the postman-governance-group repository custom property and domain mapping.
+    required: false
   requester-email:
     description: Requester email for audit context
     required: false
@@ -54,16 +57,47 @@ inputs:
       this input to see available sub-teams listed in the error output.
     required: false
   spec-url:
-    description: URL to the OpenAPI document to bootstrap
-    required: true
+    description: HTTPS URL to the OpenAPI document to bootstrap. Provide either spec-url or spec-path.
+    required: false
+  spec-path:
+    description: Local filesystem path to the OpenAPI document (relative to the workspace). Provide either spec-url or spec-path.
+    required: false
   openapi-version:
     description: OpenAPI specification version override (3.0 or 3.1). When not set, the version is auto-detected from the spec content.
     required: false
     default: ''
+  breaking-change-mode:
+    description: OpenAPI breaking-change comparison mode (off, pr-native, baseline-only, or previous-spec)
+    required: false
+    default: 'off'
+  breaking-baseline-spec-path:
+    description: Workspace-relative baseline OpenAPI spec path used by baseline-only mode and pr-native fallback
+    required: false
+  breaking-rules-path:
+    description: Workspace-relative openapi-changes rules file. Missing files are ignored.
+    required: false
+    default: changes-rules.yaml
+  breaking-target-ref:
+    description: Optional target branch or git ref override for pr-native breaking-change comparisons
+    required: false
+  breaking-summary-path:
+    description: Optional markdown report output path. Defaults to a runner-temp file.
+    required: false
+    default: ''
+  breaking-log-path:
+    description: Optional raw command log output path. Defaults to a runner-temp file.
+    required: false
+    default: ''
   governance-mapping-json:
-    description: JSON map of business domain to governance group name
+    description: Legacy JSON map of business domain to governance group name. Prefer governance-group or the postman-governance-group repository custom property.
     required: false
     default: '{}'
+  github-token:
+    description: GitHub token used to read the postman-governance-group repository custom property
+    required: false
+  gh-fallback-token:
+    description: Fallback GitHub token used to read repository custom properties when github-token cannot
+    required: false
   postman-api-key:
     description: Postman API key used for bootstrap operations
     required: true
@@ -109,6 +143,10 @@ outputs:
     description: JSON summary of generated collections
   lint-summary-json:
     description: JSON summary of lint errors and warnings
+  breaking-change-status:
+    description: OpenAPI breaking-change check status
+  breaking-change-summary-json:
+    description: JSON summary of the OpenAPI breaking-change check
 runs:
   using: node24
-  main: dist/index.cjs
+  main: dist/action.cjs