@postman-cse/onboarding-bootstrap 0.12.0 → 0.13.1

package/README.md

@@ -1,13 +1,13 @@
 # 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)
 - lint the uploaded spec by UID with the Postman CLI
@@ -16,12 +16,12 @@ This action preserves the bootstrap slice of the API Catalog demo flow:
 - 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 +87,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 +124,21 @@ 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.
+
 ## Usage
 
 ```yaml
@@ -110,7 +149,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 +158,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 +229,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. |
@@ -222,7 +262,7 @@ Install globally:
 npm install -g @postman-cse/onboarding-bootstrap
 ```
 
-The CLI package supports Node.js 20+. The examples below use Node.js 24 to match the GitHub Action runtime.
+The CLI package supports Node.js 24+ to match the GitHub Action runtime.
 
 Basic usage:
 
@@ -298,16 +338,20 @@ 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`. |
+| `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 +450,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:**
 
@@ -462,11 +506,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,25 @@ 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: ''
   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
@@ -86,6 +98,10 @@ inputs:
     description: Determines how requests are named in generated collections (Fallback or URL)
     required: false
     default: Fallback
+  postman-stack:
+    description: Postman stack profile
+    required: false
+    default: prod
 outputs:
   workspace-id:
     description: Postman workspace ID
@@ -107,4 +123,4 @@ outputs:
     description: JSON summary of lint errors and warnings
 runs:
   using: node24
-  main: dist/index.cjs
+  main: dist/action.cjs