@postman-cse/onboarding-repo-sync 0.10.1 → 0.12.0

package/README.md

@@ -9,7 +9,7 @@ Retained from finalize:
 - Create or update Postman environments from runtime URLs.
 - Associate Postman environments to system environments through Bifrost.
 - Create mock servers and smoke monitors from generated collections.
-- Export Postman collections in the Collection v3 multi-file YAML directory structure under `postman/collections/` (e.g., `[Baseline] <name>/collection.yaml`, nested folder and request YAML files). Persist repo variables and export environments into the repository under `postman/` and `.postman/`.
+- Export Postman collections in the Collection v3 multi-file YAML directory structure under `postman/collections/` (e.g., `[Baseline] <name>/collection.yaml`, nested folder and request YAML files), and export environments plus `.postman/resources.yaml` into the repository.
 - Link the Postman workspace to the repository (GitHub or GitLab) through Bifrost.
 - Commit synced artifacts and push them back to the current checked out ref.
 
@@ -205,6 +205,41 @@ If the action writes `.github/workflows/ci.yml`, provide a credential source tha
 
 Collections are exported in the Postman Collection v3 format, producing a multi-file YAML directory structure under `postman/collections/`. Each collection (Baseline, Smoke, Contract) gets its own directory containing `collection.yaml` and nested folder/request YAML files. The `.postman/resources.yaml` manifest maps each v3 collection directory to its Postman UID.
 
+The generated CI workflow reads `.postman/resources.yaml` directly to resolve the smoke/contract collection IDs and environment ID for Postman CLI runs. It does not depend on repository variables for those asset mappings.
+
+To match the app scaffold more closely, repo-sync also ensures these directories exist under `postman/`:
+
+- `collections`
+- `environments`
+- `flows`
+- `globals`
+- `mocks`
+- `specs`
+
+It also writes `postman/globals/workspace.globals.yaml` when missing.
+
+Folder and request **names are truncated to 120 characters** per path segment when writing files (with an ellipsis). That avoids `ENAMETOOLONG` when Postman item names are very long (for example, copied from long OpenAPI operation summaries).
+
+### Local spec metadata
+
+Repo-sync now scans the repository for local OpenAPI files and records them in `.postman/resources.yaml` under `localResources.specs`.
+
+- If `spec-path` is provided, it is used as the preferred local spec for `cloudResources.specs` and `.postman/workflows.yaml`.
+- If `spec-path` is omitted and exactly one local OpenAPI file is found, that file is used automatically.
+- If the local spec target is ambiguous or missing, repo-sync skips the spec cloud map and `workflows.yaml` rather than emitting incorrect relationships.
+
+When a local spec file and exported collections are both available, repo-sync writes `.postman/workflows.yaml` with `syncSpecToCollection` entries so the spec↔collection relationship metadata matches the app more closely.
+
+### Lifecycle and versioning
+
+`collection-sync-mode` controls collection lifecycle behavior:
+
+- `refresh` (default): always refresh assets and rewrite `.postman/resources.yaml` for the checked-out ref.
+- `reuse`: reuse existing assets from explicit inputs or the checked-out ref's `.postman/resources.yaml`.
+- `version`: require a release label (`release-label` input or `github-ref-name`), suffix collection export directories and mock/monitor names with that release label, and reuse only the checked-out ref's `.postman/resources.yaml` mappings.
+
+`spec-sync-mode` supports `update` (default) and `version`. If either sync mode is `version`, this action requires a derived or explicit release label.
+
 ## Inputs
 
 | Input | Default | Notes |
@@ -214,16 +249,20 @@ Collections are exported in the Postman Collection v3 format, producing a multi-
 | `project-name` | | Service name used for environments, mock servers, and monitors. |
 | `workspace-id` | | Workspace identifier used for workspace-link and export metadata. |
 | `baseline-collection-id` | | Baseline collection exported into the repo and used for mock generation. |
-| `monitor-type` | `cloud` | Type of monitor to create (`cloud` or `cli`). `cli` uses GitHub Actions cron.
+| `monitor-type` | `cloud` | Type of monitor to create (`cloud` or `cli`). `cli` uses GitHub Actions cron. |
 | `smoke-collection-id` | | Smoke collection used for monitor creation. |
 | `contract-collection-id` | | Contract collection exported into the repo. |
+| `collection-sync-mode` | `refresh` | Collection lifecycle mode: `refresh`, `reuse`, or `version`. |
+| `spec-sync-mode` | `update` | Spec lifecycle mode: `update` or `version`. |
+| `release-label` | | Optional release label for versioned naming. Falls back to `github-ref-name` when omitted. |
+| `spec-path` | | Optional repo-root-relative path to the local spec file for `resources.yaml` and `workflows.yaml` metadata. |
 | `environments-json` | `["prod"]` | Environment slugs to create or update. |
 | `repo-url` | | Explicit repository URL (GitHub or GitLab). Defaults to `https://github.com/$GITHUB_REPOSITORY` on GitHub Actions, or `$CI_PROJECT_URL` on GitLab CI. |
 | `integration-backend` | `bifrost` | Public open-alpha starts with Bifrost only. |
 | `workspace-link-enabled` | `true` | Keeps workspace linking in scope. |
 | `environment-sync-enabled` | `true` | Keeps environment association in scope by default for the open-alpha demonstration path. |
 | `system-env-map-json` | `{}` | JSON map of environment slug to system environment id. |
-| `environment-uids-json` | `{}` | JSON map of environment slug to Postman environment uid. |
+| `environment-uids-json` | `{}` | Optional explicit JSON map of environment slug to Postman environment uid. |
 | `env-runtime-urls-json` | `{}` | JSON map of environment slug to runtime base URL. |
 | `artifact-dir` | `postman` | Root directory for exported Postman artifacts. |
 | `repo-write-mode` | `commit-and-push` | Generates files and pushes with current-ref semantics. |
@@ -236,11 +275,22 @@ Collections are exported in the Postman Collection v3 format, producing a multi-
 | `ssl-client-key` | | Base64-encoded private key paired with `ssl-client-cert`. |
 | `ssl-client-passphrase` | | Optional passphrase for the client key. |
 | `ssl-extra-ca-certs` | | Base64-encoded extra CA certificates used to trust private certificate chains. |
-| `github-token` | | GitHub token for repo variables and commits. |
+| `github-token` | | GitHub token for commits, workflow updates, and optional secret persistence. |
 | `gh-fallback-token` | | Fallback GitHub token for workflow-file and variable APIs. |
-| `github-auth-mode` | `github_token_first` | GitHub auth mode for repo variable APIs. |
 | `ci-workflow-base64` | | Optional base64-encoded workflow content that overrides the built-in CI template. |
 
+### Contract smoke monitoring
+
+This repo includes `.github/workflows/contract-smoke.yml`, a scheduled live contract check for the Postman and Bifrost endpoints used by repo-sync.
+
+Configure these repository secrets before enabling the workflow:
+
+- `SMOKE_ORG_API_KEY`
+- `SMOKE_ORG_ACCESS_TOKEN`
+- `SMOKE_NON_ORG_API_KEY`
+
+The smoke workflow verifies `/me`, `/teams`, and Bifrost API key creation so upstream auth or response-shape changes are caught before they break repo-sync runs.
+
 ### Obtaining `postman-api-key`
 
 The `postman-api-key` is a Postman API key (PMAK) used for all standard Postman API operations — creating workspaces, uploading specs, generating collections, exporting artifacts, and managing environments.

package/action.yml

@@ -29,6 +29,17 @@ inputs:
   contract-collection-id:
     description: Contract collection ID used for exported artifacts.
     required: false
+  collection-sync-mode:
+    description: Collection sync lifecycle mode (refresh, reuse, or version).
+    required: false
+    default: refresh
+  spec-sync-mode:
+    description: Spec sync lifecycle mode (update or version).
+    required: false
+    default: update
+  release-label:
+    description: Optional release label used for versioned naming.
+    required: false
   monitor-id:
     description: Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one.
     required: false
@@ -101,10 +112,6 @@ inputs:
   gh-fallback-token:
     description: Fallback token for repository variable APIs and workflow-file pushes.
     required: false
-  github-auth-mode:
-    description: GitHub auth mode for repository variable APIs.
-    required: false
-    default: github_token_first
   org-mode:
     description: Whether the Postman team uses org-mode. When true, x-entity-team-id header is included in Bifrost proxy calls. Non-org teams must omit this header.
     required: false
@@ -124,6 +131,12 @@ inputs:
   ssl-extra-ca-certs:
     description: Optional base64-encoded PEM CA certificate bundle for custom trust.
     required: false
+  spec-id:
+    description: Spec UID from bootstrap, persisted into .postman/resources.yaml cloudResources.
+    required: false
+  spec-path:
+    description: Optional repo-root-relative path to the local spec file for resources/workflows metadata.
+    required: false
 outputs:
   integration-backend:
     description: Resolved integration backend for the open-alpha run.