@postman-cse/onboarding-bootstrap 0.10.0 → 0.11.0

package/README.md

@@ -202,6 +202,7 @@ steps:
 | `baseline-collection-id` | | Reuse an existing baseline collection. |
 | `smoke-collection-id` | | Reuse an existing smoke collection. |
 | `contract-collection-id` | | Reuse an existing contract collection. |
+| `sync-examples` | `true` | Whether linked spec/collection relations should enable example syncing during cloud linkage. |
 | `collection-sync-mode` | `refresh` | Collection lifecycle policy. `reuse` keeps existing collections, `refresh` regenerates the current collection set from the latest spec, and `version` creates or reuses release-scoped collections. |
 | `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. |
@@ -247,6 +248,14 @@ Current Postman asset state lives in `.postman/resources.yaml`.
 - `update` and `reuse` modes resolve current-state mappings from the checked-out ref.
 - `version` mode reuses only the checked-out ref's mappings; release history lives in git history and tags, not in a separate manifest file or repository variables.
 
+### Cloud spec-to-collection syncing
+
+After collections exist, bootstrap links them to the cloud specification and triggers a spec-side collection sync when `postman-access-token` is available.
+
+- `sync-examples: true` (default) enables example syncing in that relation setup.
+- `sync-examples: false` keeps the relation but disables example syncing.
+- If `postman-access-token` is missing, bootstrap warns and skips the cloud link/sync step.
+
 ### Contract smoke monitoring
 
 This repo includes `.github/workflows/contract-smoke.yml`, a scheduled live contract check for the upstream Postman APIs used by bootstrap.

package/action.yml

@@ -17,6 +17,10 @@ inputs:
   contract-collection-id:
     description: Existing contract collection ID
     required: false
+  sync-examples:
+    description: Whether linked spec/collection relations should enable example syncing
+    required: false
+    default: 'true'
   collection-sync-mode:
     description: Collection lifecycle policy (reuse, refresh, or version)
     required: false

package/dist/cli.cjs

@@ -28728,6 +28728,12 @@ var openAlphaActionContract = {
       description: "Existing contract collection ID.",
       required: false
     },
+    "sync-examples": {
+      description: "Whether linked spec/collection relations should enable example syncing.",
+      required: false,
+      default: "true",
+      allowedValues: ["true", "false"]
+    },
     "collection-sync-mode": {
       description: "Collection lifecycle policy: reuse existing collections, refresh them from the latest spec, or version them by release label.",
       required: false,
@@ -29659,6 +29665,26 @@ var BifrostInternalIntegrationAdapter = class {
       options.workerBaseUrl || "https://catalog-admin.postman-account2009.workers.dev"
     ).replace(/\/+$/, "");
   }
+  async proxyRequest(service, method, requestPath, body) {
+    const url = "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy";
+    const headers = {
+      "Content-Type": "application/json",
+      "x-access-token": this.accessToken
+    };
+    if (this.teamId) {
+      headers["x-entity-team-id"] = this.teamId;
+    }
+    return this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        service,
+        method,
+        path: requestPath,
+        ...body !== void 0 ? { body } : {}
+      })
+    });
+  }
   async assignWorkspaceToGovernanceGroup(workspaceId, domain, mappingJson) {
     let mapping;
     try {
@@ -29752,14 +29778,6 @@ var BifrostInternalIntegrationAdapter = class {
     }
   }
   async connectWorkspaceToRepository(workspaceId, repoUrl) {
-    const url = "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy";
-    const headers = {
-      "Content-Type": "application/json",
-      "x-access-token": this.accessToken
-    };
-    if (this.teamId) {
-      headers["x-entity-team-id"] = this.teamId;
-    }
     const payload = {
       service: "workspaces",
       method: "POST",
@@ -29770,11 +29788,12 @@ var BifrostInternalIntegrationAdapter = class {
         versionControl: true
       }
     };
-    const response = await this.fetchImpl(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(payload)
-    });
+    const response = await this.proxyRequest(
+      payload.service,
+      payload.method,
+      payload.path,
+      payload.body
+    );
     if (response.ok) return;
     if (response.status === 400) {
       const body = await response.text();
@@ -29791,29 +29810,68 @@ var BifrostInternalIntegrationAdapter = class {
     }
     throw await HttpError.fromResponse(response, {
       method: "POST",
-      requestHeaders: headers,
+      requestHeaders: {
+        "Content-Type": "application/json",
+        "x-access-token": this.accessToken,
+        ...this.teamId ? { "x-entity-team-id": this.teamId } : {}
+      },
       secretValues: [this.accessToken],
-      url
+      url: "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy"
     });
   }
-  async getWorkspaceGitRepoUrl(workspaceId) {
-    const url = "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy";
-    const headers = {
-      "Content-Type": "application/json",
-      "x-access-token": this.accessToken
-    };
-    if (this.teamId) {
-      headers["x-entity-team-id"] = this.teamId;
+  async linkCollectionsToSpecification(specificationId, collections) {
+    if (collections.length === 0) {
+      return;
     }
-    const response = await this.fetchImpl(url, {
+    const response = await this.proxyRequest(
+      "specification",
+      "put",
+      `/specifications/${specificationId}/collections`,
+      collections.map((collection) => ({
+        collectionId: collection.collectionId,
+        ...collection.syncOptions ? { syncOptions: collection.syncOptions } : {}
+      }))
+    );
+    if (response.ok) {
+      return;
+    }
+    throw await HttpError.fromResponse(response, {
       method: "POST",
-      headers,
-      body: JSON.stringify({
-        service: "workspaces",
-        method: "GET",
-        path: `/workspaces/${workspaceId}/filesystem`
-      })
+      requestHeaders: {
+        "Content-Type": "application/json",
+        "x-access-token": this.accessToken,
+        ...this.teamId ? { "x-entity-team-id": this.teamId } : {}
+      },
+      secretValues: [this.accessToken],
+      url: "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy"
+    });
+  }
+  async syncCollection(specificationId, collectionId) {
+    const response = await this.proxyRequest(
+      "specification",
+      "post",
+      `/specifications/${specificationId}/collections/${collectionId}/sync`
+    );
+    if (response.ok) {
+      return;
+    }
+    throw await HttpError.fromResponse(response, {
+      method: "POST",
+      requestHeaders: {
+        "Content-Type": "application/json",
+        "x-access-token": this.accessToken,
+        ...this.teamId ? { "x-entity-team-id": this.teamId } : {}
+      },
+      secretValues: [this.accessToken],
+      url: "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy"
     });
+  }
+  async getWorkspaceGitRepoUrl(workspaceId) {
+    const response = await this.proxyRequest(
+      "workspaces",
+      "GET",
+      `/workspaces/${workspaceId}/filesystem`
+    );
     if (response.status === 404) return null;
     if (!response.ok) return null;
     const body = await response.text();
@@ -29996,6 +30054,13 @@ function requireInput(actionCore, name) {
 function optionalInput(actionCore, name) {
   return normalizeInputValue(actionCore.getInput(name));
 }
+function parseBooleanInput(value, defaultValue) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) return defaultValue;
+  if (["true", "1", "yes", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "off"].includes(normalized)) return false;
+  return defaultValue;
+}
 function parseCollectionSyncMode(value) {
   if (value === "reuse" || value === "version") {
     return value;
@@ -30040,6 +30105,7 @@ function resolveInputs(env = process.env) {
     baselineCollectionId: getInput("baseline-collection-id", env),
     smokeCollectionId: getInput("smoke-collection-id", env),
     contractCollectionId: getInput("contract-collection-id", env),
+    syncExamples: parseBooleanInput(getInput("sync-examples", env), true),
     collectionSyncMode: parseCollectionSyncMode(getInput("collection-sync-mode", env)),
     specSyncMode: parseSpecSyncMode(getInput("spec-sync-mode", env)),
     releaseLabel: getInput("release-label", env),
@@ -30099,6 +30165,7 @@ function readActionInputs(actionCore) {
     INPUT_BASELINE_COLLECTION_ID: optionalInput(actionCore, "baseline-collection-id"),
     INPUT_SMOKE_COLLECTION_ID: optionalInput(actionCore, "smoke-collection-id"),
     INPUT_CONTRACT_COLLECTION_ID: optionalInput(actionCore, "contract-collection-id"),
+    INPUT_SYNC_EXAMPLES: optionalInput(actionCore, "sync-examples") ?? openAlphaActionContract.inputs["sync-examples"].default,
     INPUT_COLLECTION_SYNC_MODE: optionalInput(actionCore, "collection-sync-mode") ?? openAlphaActionContract.inputs["collection-sync-mode"].default,
     INPUT_SPEC_SYNC_MODE: optionalInput(actionCore, "spec-sync-mode") ?? openAlphaActionContract.inputs["spec-sync-mode"].default,
     INPUT_RELEASE_LABEL: optionalInput(actionCore, "release-label"),
@@ -30671,6 +30738,48 @@ For CLI usage, pass --workspace-team-id <id> or export POSTMAN_WORKSPACE_TEAM_ID
       ]);
     }
   );
+  const linkedCollectionIds = [
+    outputs["baseline-collection-id"],
+    outputs["smoke-collection-id"],
+    outputs["contract-collection-id"]
+  ].filter(Boolean);
+  if (linkedCollectionIds.length > 0) {
+    if (dependencies.internalIntegration) {
+      await runGroup(
+        dependencies.core,
+        "Link Collections to Specification",
+        async () => {
+          await dependencies.internalIntegration?.linkCollectionsToSpecification(
+            outputs["spec-id"],
+            linkedCollectionIds.map((collectionId) => ({
+              collectionId,
+              syncOptions: {
+                syncExamples: inputs.syncExamples
+              }
+            }))
+          );
+        }
+      );
+      await runGroup(
+        dependencies.core,
+        "Sync Linked Collections",
+        async () => {
+          await Promise.all(
+            linkedCollectionIds.map(
+              (collectionId) => dependencies.internalIntegration.syncCollection(
+                outputs["spec-id"],
+                collectionId
+              )
+            )
+          );
+        }
+      );
+    } else {
+      dependencies.core.warning(
+        "Skipping cloud spec-to-collection linking and sync because postman-access-token is not configured"
+      );
+    }
+  }
   for (const [name, value] of Object.entries(outputs)) {
     dependencies.core.setOutput(name, value);
   }
@@ -30858,6 +30967,7 @@ function parseCliArgs(argv, env = process.env) {
     "baseline-collection-id",
     "smoke-collection-id",
     "contract-collection-id",
+    "sync-examples",
     "collection-sync-mode",
     "spec-sync-mode",
     "release-label",

package/dist/index.cjs

@@ -28724,6 +28724,12 @@ var openAlphaActionContract = {
       description: "Existing contract collection ID.",
       required: false
     },
+    "sync-examples": {
+      description: "Whether linked spec/collection relations should enable example syncing.",
+      required: false,
+      default: "true",
+      allowedValues: ["true", "false"]
+    },
     "collection-sync-mode": {
       description: "Collection lifecycle policy: reuse existing collections, refresh them from the latest spec, or version them by release label.",
       required: false,
@@ -29655,6 +29661,26 @@ var BifrostInternalIntegrationAdapter = class {
       options.workerBaseUrl || "https://catalog-admin.postman-account2009.workers.dev"
     ).replace(/\/+$/, "");
   }
+  async proxyRequest(service, method, requestPath, body) {
+    const url = "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy";
+    const headers = {
+      "Content-Type": "application/json",
+      "x-access-token": this.accessToken
+    };
+    if (this.teamId) {
+      headers["x-entity-team-id"] = this.teamId;
+    }
+    return this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        service,
+        method,
+        path: requestPath,
+        ...body !== void 0 ? { body } : {}
+      })
+    });
+  }
   async assignWorkspaceToGovernanceGroup(workspaceId, domain, mappingJson) {
     let mapping;
     try {
@@ -29748,14 +29774,6 @@ var BifrostInternalIntegrationAdapter = class {
     }
   }
   async connectWorkspaceToRepository(workspaceId, repoUrl) {
-    const url = "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy";
-    const headers = {
-      "Content-Type": "application/json",
-      "x-access-token": this.accessToken
-    };
-    if (this.teamId) {
-      headers["x-entity-team-id"] = this.teamId;
-    }
     const payload = {
       service: "workspaces",
       method: "POST",
@@ -29766,11 +29784,12 @@ var BifrostInternalIntegrationAdapter = class {
         versionControl: true
       }
     };
-    const response = await this.fetchImpl(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(payload)
-    });
+    const response = await this.proxyRequest(
+      payload.service,
+      payload.method,
+      payload.path,
+      payload.body
+    );
     if (response.ok) return;
     if (response.status === 400) {
       const body = await response.text();
@@ -29787,29 +29806,68 @@ var BifrostInternalIntegrationAdapter = class {
     }
     throw await HttpError.fromResponse(response, {
       method: "POST",
-      requestHeaders: headers,
+      requestHeaders: {
+        "Content-Type": "application/json",
+        "x-access-token": this.accessToken,
+        ...this.teamId ? { "x-entity-team-id": this.teamId } : {}
+      },
       secretValues: [this.accessToken],
-      url
+      url: "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy"
     });
   }
-  async getWorkspaceGitRepoUrl(workspaceId) {
-    const url = "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy";
-    const headers = {
-      "Content-Type": "application/json",
-      "x-access-token": this.accessToken
-    };
-    if (this.teamId) {
-      headers["x-entity-team-id"] = this.teamId;
+  async linkCollectionsToSpecification(specificationId, collections) {
+    if (collections.length === 0) {
+      return;
     }
-    const response = await this.fetchImpl(url, {
+    const response = await this.proxyRequest(
+      "specification",
+      "put",
+      `/specifications/${specificationId}/collections`,
+      collections.map((collection) => ({
+        collectionId: collection.collectionId,
+        ...collection.syncOptions ? { syncOptions: collection.syncOptions } : {}
+      }))
+    );
+    if (response.ok) {
+      return;
+    }
+    throw await HttpError.fromResponse(response, {
       method: "POST",
-      headers,
-      body: JSON.stringify({
-        service: "workspaces",
-        method: "GET",
-        path: `/workspaces/${workspaceId}/filesystem`
-      })
+      requestHeaders: {
+        "Content-Type": "application/json",
+        "x-access-token": this.accessToken,
+        ...this.teamId ? { "x-entity-team-id": this.teamId } : {}
+      },
+      secretValues: [this.accessToken],
+      url: "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy"
+    });
+  }
+  async syncCollection(specificationId, collectionId) {
+    const response = await this.proxyRequest(
+      "specification",
+      "post",
+      `/specifications/${specificationId}/collections/${collectionId}/sync`
+    );
+    if (response.ok) {
+      return;
+    }
+    throw await HttpError.fromResponse(response, {
+      method: "POST",
+      requestHeaders: {
+        "Content-Type": "application/json",
+        "x-access-token": this.accessToken,
+        ...this.teamId ? { "x-entity-team-id": this.teamId } : {}
+      },
+      secretValues: [this.accessToken],
+      url: "https://bifrost-premium-https-v4.gw.postman.com/ws/proxy"
     });
+  }
+  async getWorkspaceGitRepoUrl(workspaceId) {
+    const response = await this.proxyRequest(
+      "workspaces",
+      "GET",
+      `/workspaces/${workspaceId}/filesystem`
+    );
     if (response.status === 404) return null;
     if (!response.ok) return null;
     const body = await response.text();
@@ -29992,6 +30050,13 @@ function requireInput(actionCore, name) {
 function optionalInput(actionCore, name) {
   return normalizeInputValue(actionCore.getInput(name));
 }
+function parseBooleanInput(value, defaultValue) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) return defaultValue;
+  if (["true", "1", "yes", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "off"].includes(normalized)) return false;
+  return defaultValue;
+}
 function parseCollectionSyncMode(value) {
   if (value === "reuse" || value === "version") {
     return value;
@@ -30036,6 +30101,7 @@ function resolveInputs(env = process.env) {
     baselineCollectionId: getInput("baseline-collection-id", env),
     smokeCollectionId: getInput("smoke-collection-id", env),
     contractCollectionId: getInput("contract-collection-id", env),
+    syncExamples: parseBooleanInput(getInput("sync-examples", env), true),
     collectionSyncMode: parseCollectionSyncMode(getInput("collection-sync-mode", env)),
     specSyncMode: parseSpecSyncMode(getInput("spec-sync-mode", env)),
     releaseLabel: getInput("release-label", env),
@@ -30095,6 +30161,7 @@ function readActionInputs(actionCore) {
     INPUT_BASELINE_COLLECTION_ID: optionalInput(actionCore, "baseline-collection-id"),
     INPUT_SMOKE_COLLECTION_ID: optionalInput(actionCore, "smoke-collection-id"),
     INPUT_CONTRACT_COLLECTION_ID: optionalInput(actionCore, "contract-collection-id"),
+    INPUT_SYNC_EXAMPLES: optionalInput(actionCore, "sync-examples") ?? openAlphaActionContract.inputs["sync-examples"].default,
     INPUT_COLLECTION_SYNC_MODE: optionalInput(actionCore, "collection-sync-mode") ?? openAlphaActionContract.inputs["collection-sync-mode"].default,
     INPUT_SPEC_SYNC_MODE: optionalInput(actionCore, "spec-sync-mode") ?? openAlphaActionContract.inputs["spec-sync-mode"].default,
     INPUT_RELEASE_LABEL: optionalInput(actionCore, "release-label"),
@@ -30667,6 +30734,48 @@ For CLI usage, pass --workspace-team-id <id> or export POSTMAN_WORKSPACE_TEAM_ID
       ]);
     }
   );
+  const linkedCollectionIds = [
+    outputs["baseline-collection-id"],
+    outputs["smoke-collection-id"],
+    outputs["contract-collection-id"]
+  ].filter(Boolean);
+  if (linkedCollectionIds.length > 0) {
+    if (dependencies.internalIntegration) {
+      await runGroup(
+        dependencies.core,
+        "Link Collections to Specification",
+        async () => {
+          await dependencies.internalIntegration?.linkCollectionsToSpecification(
+            outputs["spec-id"],
+            linkedCollectionIds.map((collectionId) => ({
+              collectionId,
+              syncOptions: {
+                syncExamples: inputs.syncExamples
+              }
+            }))
+          );
+        }
+      );
+      await runGroup(
+        dependencies.core,
+        "Sync Linked Collections",
+        async () => {
+          await Promise.all(
+            linkedCollectionIds.map(
+              (collectionId) => dependencies.internalIntegration.syncCollection(
+                outputs["spec-id"],
+                collectionId
+              )
+            )
+          );
+        }
+      );
+    } else {
+      dependencies.core.warning(
+        "Skipping cloud spec-to-collection linking and sync because postman-access-token is not configured"
+      );
+    }
+  }
   for (const [name, value] of Object.entries(outputs)) {
     dependencies.core.setOutput(name, value);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-bootstrap",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Public open-alpha Postman bootstrap GitHub Action.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/cli.ts

@@ -191,6 +191,7 @@ export function parseCliArgs(argv: string[], env: NodeJS.ProcessEnv = process.en
     'baseline-collection-id',
     'smoke-collection-id',
     'contract-collection-id',
+    'sync-examples',
     'collection-sync-mode',
     'spec-sync-mode',
     'release-label',

package/src/contracts.ts

@@ -43,6 +43,12 @@ export const openAlphaActionContract: BetaActionContract = {
       description: 'Existing contract collection ID.',
       required: false
     },
+    'sync-examples': {
+      description: 'Whether linked spec/collection relations should enable example syncing.',
+      required: false,
+      default: 'true',
+      allowedValues: ['true', 'false']
+    },
     'collection-sync-mode': {
       description:
         'Collection lifecycle policy: reuse existing collections, refresh them from the latest spec, or version them by release label.',

package/src/index.ts

@@ -19,6 +19,7 @@ export interface ResolvedInputs {
   baselineCollectionId?: string;
   smokeCollectionId?: string;
   contractCollectionId?: string;
+  syncExamples: boolean;
   collectionSyncMode: 'reuse' | 'refresh' | 'version';
   specSyncMode: 'update' | 'version';
   releaseLabel?: string;
@@ -101,7 +102,7 @@ export interface BootstrapExecutionDependencies {
   io: IOLike;
   internalIntegration?: Pick<
     InternalIntegrationAdapter,
-    'assignWorkspaceToGovernanceGroup'
+    'assignWorkspaceToGovernanceGroup' | 'linkCollectionsToSpecification' | 'syncCollection'
   >;
   postman: Pick<
     PostmanAssetsClient,
@@ -250,6 +251,7 @@ export function resolveInputs(
     baselineCollectionId: getInput('baseline-collection-id', env),
     smokeCollectionId: getInput('smoke-collection-id', env),
     contractCollectionId: getInput('contract-collection-id', env),
+    syncExamples: parseBooleanInput(getInput('sync-examples', env), true),
     collectionSyncMode: parseCollectionSyncMode(getInput('collection-sync-mode', env)),
     specSyncMode: parseSpecSyncMode(getInput('spec-sync-mode', env)),
     releaseLabel: getInput('release-label', env),
@@ -322,6 +324,9 @@ export function readActionInputs(
     INPUT_BASELINE_COLLECTION_ID: optionalInput(actionCore, 'baseline-collection-id'),
     INPUT_SMOKE_COLLECTION_ID: optionalInput(actionCore, 'smoke-collection-id'),
     INPUT_CONTRACT_COLLECTION_ID: optionalInput(actionCore, 'contract-collection-id'),
+    INPUT_SYNC_EXAMPLES:
+      optionalInput(actionCore, 'sync-examples') ??
+      openAlphaActionContract.inputs['sync-examples'].default,
     INPUT_COLLECTION_SYNC_MODE:
       optionalInput(actionCore, 'collection-sync-mode') ??
       openAlphaActionContract.inputs['collection-sync-mode'].default,
@@ -1025,6 +1030,51 @@ export async function runBootstrap(
     }
   );
 
+  const linkedCollectionIds = [
+    outputs['baseline-collection-id'],
+    outputs['smoke-collection-id'],
+    outputs['contract-collection-id']
+  ].filter(Boolean);
+
+  if (linkedCollectionIds.length > 0) {
+    if (dependencies.internalIntegration) {
+      await runGroup(
+        dependencies.core,
+        'Link Collections to Specification',
+        async () => {
+          await dependencies.internalIntegration?.linkCollectionsToSpecification(
+            outputs['spec-id'],
+            linkedCollectionIds.map((collectionId) => ({
+              collectionId,
+              syncOptions: {
+                syncExamples: inputs.syncExamples
+              }
+            }))
+          );
+        }
+      );
+
+      await runGroup(
+        dependencies.core,
+        'Sync Linked Collections',
+        async () => {
+          await Promise.all(
+            linkedCollectionIds.map((collectionId) =>
+              dependencies.internalIntegration!.syncCollection(
+                outputs['spec-id'],
+                collectionId
+              )
+            )
+          );
+        }
+      );
+    } else {
+      dependencies.core.warning(
+        'Skipping cloud spec-to-collection linking and sync because postman-access-token is not configured'
+      );
+    }
+  }
+
   for (const [name, value] of Object.entries(outputs)) {
     dependencies.core.setOutput(name, value);
   }

package/src/lib/postman/internal-integration-adapter.ts

@@ -9,6 +9,13 @@ export interface GovernanceAssociation {
   systemEnvId: string;
 }
 
+export interface SpecificationCollectionLink {
+  collectionId: string;
+  syncOptions?: {
+    syncExamples: boolean;
+  };
+}
+
 export interface InternalIntegrationAdapterOptions {
   accessToken: string;
   backend: string;
@@ -32,6 +39,14 @@ export interface InternalIntegrationAdapter {
     workspaceId: string,
     repoUrl: string
   ): Promise<void>;
+  linkCollectionsToSpecification(
+    specificationId: string,
+    collections: SpecificationCollectionLink[]
+  ): Promise<void>;
+  syncCollection(
+    specificationId: string,
+    collectionId: string
+  ): Promise<void>;
 }
 
 class BifrostInternalIntegrationAdapter implements InternalIntegrationAdapter {
@@ -53,6 +68,33 @@ class BifrostInternalIntegrationAdapter implements InternalIntegrationAdapter {
     ).replace(/\/+$/, '');
   }
 
+  private async proxyRequest(
+    service: string,
+    method: string,
+    requestPath: string,
+    body?: unknown
+  ): Promise<Response> {
+    const url = 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy';
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'x-access-token': this.accessToken
+    };
+    if (this.teamId) {
+      headers['x-entity-team-id'] = this.teamId;
+    }
+
+    return this.fetchImpl(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        service,
+        method,
+        path: requestPath,
+        ...(body !== undefined ? { body } : {})
+      })
+    });
+  }
+
   async assignWorkspaceToGovernanceGroup(
     workspaceId: string,
     domain: string,
@@ -168,14 +210,6 @@ class BifrostInternalIntegrationAdapter implements InternalIntegrationAdapter {
     workspaceId: string,
     repoUrl: string
   ): Promise<void> {
-    const url = 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy';
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-      'x-access-token': this.accessToken
-    };
-    if (this.teamId) {
-      headers['x-entity-team-id'] = this.teamId;
-    }
     const payload = {
       service: 'workspaces',
       method: 'POST',
@@ -187,11 +221,12 @@ class BifrostInternalIntegrationAdapter implements InternalIntegrationAdapter {
       }
     };
 
-    const response = await this.fetchImpl(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(payload)
-    });
+    const response = await this.proxyRequest(
+      payload.service,
+      payload.method,
+      payload.path,
+      payload.body
+    );
 
     if (response.ok) return;
 
@@ -215,31 +250,82 @@ class BifrostInternalIntegrationAdapter implements InternalIntegrationAdapter {
 
     throw await HttpError.fromResponse(response, {
       method: 'POST',
-      requestHeaders: headers,
+      requestHeaders: {
+        'Content-Type': 'application/json',
+        'x-access-token': this.accessToken,
+        ...(this.teamId ? { 'x-entity-team-id': this.teamId } : {})
+      },
       secretValues: [this.accessToken],
-      url
+      url: 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy'
     });
   }
 
-  private async getWorkspaceGitRepoUrl(workspaceId: string): Promise<string | null> {
-    const url = 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy';
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-      'x-access-token': this.accessToken
-    };
-    if (this.teamId) {
-      headers['x-entity-team-id'] = this.teamId;
+  async linkCollectionsToSpecification(
+    specificationId: string,
+    collections: SpecificationCollectionLink[]
+  ): Promise<void> {
+    if (collections.length === 0) {
+      return;
     }
 
-    const response = await this.fetchImpl(url, {
+    const response = await this.proxyRequest(
+      'specification',
+      'put',
+      `/specifications/${specificationId}/collections`,
+      collections.map((collection) => ({
+        collectionId: collection.collectionId,
+        ...(collection.syncOptions ? { syncOptions: collection.syncOptions } : {})
+      }))
+    );
+
+    if (response.ok) {
+      return;
+    }
+
+    throw await HttpError.fromResponse(response, {
       method: 'POST',
-      headers,
-      body: JSON.stringify({
-        service: 'workspaces',
-        method: 'GET',
-        path: `/workspaces/${workspaceId}/filesystem`
-      })
+      requestHeaders: {
+        'Content-Type': 'application/json',
+        'x-access-token': this.accessToken,
+        ...(this.teamId ? { 'x-entity-team-id': this.teamId } : {})
+      },
+      secretValues: [this.accessToken],
+      url: 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy'
     });
+  }
+
+  async syncCollection(
+    specificationId: string,
+    collectionId: string
+  ): Promise<void> {
+    const response = await this.proxyRequest(
+      'specification',
+      'post',
+      `/specifications/${specificationId}/collections/${collectionId}/sync`
+    );
+
+    if (response.ok) {
+      return;
+    }
+
+    throw await HttpError.fromResponse(response, {
+      method: 'POST',
+      requestHeaders: {
+        'Content-Type': 'application/json',
+        'x-access-token': this.accessToken,
+        ...(this.teamId ? { 'x-entity-team-id': this.teamId } : {})
+      },
+      secretValues: [this.accessToken],
+      url: 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy'
+    });
+  }
+
+  private async getWorkspaceGitRepoUrl(workspaceId: string): Promise<string | null> {
+    const response = await this.proxyRequest(
+      'workspaces',
+      'GET',
+      `/workspaces/${workspaceId}/filesystem`
+    );
 
     if (response.status === 404) return null;
     if (!response.ok) return null;

package/tests/bootstrap-action.test.ts

@@ -60,6 +60,7 @@ function createCoreStub(values: Record<string, string> = {}) {
 function createInputs(overrides: Partial<ResolvedInputs> = {}): ResolvedInputs {
   return {
     projectName: 'core-payments',
+    syncExamples: true,
     collectionSyncMode: 'refresh',
     specSyncMode: 'update',
     releaseLabel: undefined,
@@ -148,7 +149,9 @@ describe('bootstrap action', () => {
       getSpecContent: vi.fn().mockResolvedValue('openapi: 3.1.0')
     };
     const internalIntegration = {
-      assignWorkspaceToGovernanceGroup: vi.fn().mockResolvedValue(undefined)
+      assignWorkspaceToGovernanceGroup: vi.fn().mockResolvedValue(undefined),
+      linkCollectionsToSpecification: vi.fn().mockResolvedValue(undefined),
+      syncCollection: vi.fn().mockResolvedValue(undefined)
     };
     const specFetcher = vi.fn<typeof fetch>().mockResolvedValue(
       new Response('openapi: 3.1.0', {
@@ -177,6 +180,29 @@ describe('bootstrap action', () => {
     );
     expect(postman.addAdminsToWorkspace).toHaveBeenCalledWith('ws-123', '101,102');
     expect(order).toEqual(['[Baseline]', '[Smoke]', '[Contract]']);
+    expect(internalIntegration.linkCollectionsToSpecification).toHaveBeenCalledWith(
+      'spec-123',
+      [
+        { collectionId: 'col-baseline', syncOptions: { syncExamples: true } },
+        { collectionId: 'col-smoke', syncOptions: { syncExamples: true } },
+        { collectionId: 'col-contract', syncOptions: { syncExamples: true } }
+      ]
+    );
+    expect(internalIntegration.syncCollection).toHaveBeenNthCalledWith(
+      1,
+      'spec-123',
+      'col-baseline'
+    );
+    expect(internalIntegration.syncCollection).toHaveBeenNthCalledWith(
+      2,
+      'spec-123',
+      'col-smoke'
+    );
+    expect(internalIntegration.syncCollection).toHaveBeenNthCalledWith(
+      3,
+      'spec-123',
+      'col-contract'
+    );
     expect(result).toMatchObject({
       'workspace-id': 'ws-123',
       'workspace-name': '[AF] core-payments',
@@ -730,7 +756,7 @@ describe('bootstrap action', () => {
   });
 
   it('skips governance assignment when postman-access-token is absent', async () => {
-    const { core } = createCoreStub();
+    const { core, warnings } = createCoreStub();
     const execStub = createExecStub();
     const ioStub = createIoStub();
     const postman = {
@@ -764,6 +790,64 @@ describe('bootstrap action', () => {
 
     expect(result['workspace-id']).toBe('ws-123');
     expect(postman.createWorkspace).toHaveBeenCalled();
+    expect(
+      warnings.some((warning) =>
+        warning.includes('Skipping cloud spec-to-collection linking and sync because postman-access-token is not configured')
+      )
+    ).toBe(true);
+  });
+
+  it('passes syncExamples=false when configured', async () => {
+    const { core } = createCoreStub();
+    const execStub = createExecStub();
+    const ioStub = createIoStub();
+    const postman = {
+      addAdminsToWorkspace: vi.fn().mockResolvedValue(undefined),
+      createWorkspace: vi.fn().mockResolvedValue({ id: 'ws-123' }),
+      findWorkspacesByName: vi.fn().mockResolvedValue([]),
+      generateCollection: vi
+        .fn()
+        .mockResolvedValueOnce('col-baseline')
+        .mockResolvedValueOnce('col-smoke')
+        .mockResolvedValueOnce('col-contract'),
+      getAutoDerivedTeamId: vi.fn().mockResolvedValue('12345'),
+      getTeams: vi.fn().mockResolvedValue([]),
+      getWorkspaceGitRepoUrl: vi.fn().mockResolvedValue(null),
+      injectTests: vi.fn().mockResolvedValue(undefined),
+      inviteRequesterToWorkspace: vi.fn().mockResolvedValue(undefined),
+      tagCollection: vi.fn().mockResolvedValue(undefined),
+      uploadSpec: vi.fn().mockResolvedValue('spec-123'),
+      updateSpec: vi.fn().mockResolvedValue(undefined),
+      getSpecContent: vi.fn().mockResolvedValue('openapi: 3.1.0')
+    };
+    const internalIntegration = {
+      assignWorkspaceToGovernanceGroup: vi.fn().mockResolvedValue(undefined),
+      linkCollectionsToSpecification: vi.fn().mockResolvedValue(undefined),
+      syncCollection: vi.fn().mockResolvedValue(undefined)
+    };
+
+    await runBootstrap(
+      createInputs({ syncExamples: false }),
+      {
+        core,
+        exec: execStub,
+        io: ioStub,
+        internalIntegration,
+        postman,
+        specFetcher: vi.fn<typeof fetch>().mockResolvedValue(
+          new Response('openapi: 3.1.0', { status: 200 })
+        )
+      }
+    );
+
+    expect(internalIntegration.linkCollectionsToSpecification).toHaveBeenCalledWith(
+      'spec-123',
+      [
+        { collectionId: 'col-baseline', syncOptions: { syncExamples: false } },
+        { collectionId: 'col-smoke', syncOptions: { syncExamples: false } },
+        { collectionId: 'col-contract', syncOptions: { syncExamples: false } }
+      ]
+    );
   });
 
   it('runs without any GitHub dependency', async () => {

package/tests/cli.test.ts

@@ -14,6 +14,8 @@ describe('parseCliArgs', () => {
         'pmak-test',
         '--workspace-admin-user-ids',
         '101,102',
+        '--sync-examples',
+        'false',
         '--collection-sync-mode',
         'version',
         '--spec-sync-mode',
@@ -36,6 +38,7 @@ describe('parseCliArgs', () => {
     expect(config.inputEnv.INPUT_SPEC_URL).toBe('https://example.test/openapi.yaml');
     expect(config.inputEnv.INPUT_POSTMAN_API_KEY).toBe('pmak-test');
     expect(config.inputEnv.INPUT_WORKSPACE_ADMIN_USER_IDS).toBe('101,102');
+    expect(config.inputEnv.INPUT_SYNC_EXAMPLES).toBe('false');
     expect(config.inputEnv.INPUT_COLLECTION_SYNC_MODE).toBe('version');
     expect(config.inputEnv.INPUT_SPEC_SYNC_MODE).toBe('version');
     expect(config.inputEnv.INPUT_RELEASE_LABEL).toBe('v1.2.3');

package/tests/contract.test.ts

@@ -42,6 +42,14 @@ describe('open-alpha action contract', () => {
   });
 
   it('defaults lifecycle controls in contract, manifest, and runtime', () => {
+    expect(openAlphaActionContract.inputs['sync-examples'].default).toBe('true');
+    expect(openAlphaActionContract.inputs['sync-examples'].allowedValues).toEqual([
+      'true',
+      'false'
+    ]);
+    expect(actionManifest.inputs['sync-examples'].default).toBe('true');
+    expect(resolveInputs({}).syncExamples).toBe(true);
+
     expect(openAlphaActionContract.inputs['collection-sync-mode'].default).toBe('refresh');
     expect(openAlphaActionContract.inputs['collection-sync-mode'].allowedValues).toEqual([
       'reuse',

package/tests/internal-integration-adapter.test.ts

@@ -184,6 +184,75 @@ describe('internal integration adapter', () => {
     );
   });
 
+  it('routes specification collection linking through the Bifrost proxy with sync options', async () => {
+    const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(
+      jsonResponse({ data: { updated: 1 } })
+    );
+
+    const adapter = createInternalIntegrationAdapter({
+      backend: 'bifrost',
+      accessToken: 'token-123',
+      teamId: '11430732',
+      fetchImpl
+    });
+
+    await adapter.linkCollectionsToSpecification('spec-123', [
+      {
+        collectionId: 'col-1',
+        syncOptions: { syncExamples: true }
+      }
+    ]);
+
+    expect(fetchImpl).toHaveBeenCalledWith(
+      'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy',
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({
+          'x-access-token': 'token-123',
+          'x-entity-team-id': '11430732'
+        }),
+        body: JSON.stringify({
+          service: 'specification',
+          method: 'put',
+          path: '/specifications/spec-123/collections',
+          body: [
+            {
+              collectionId: 'col-1',
+              syncOptions: { syncExamples: true }
+            }
+          ]
+        })
+      })
+    );
+  });
+
+  it('routes specification collection sync through the Bifrost proxy', async () => {
+    const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(
+      jsonResponse({ data: { taskId: 'task-1' } })
+    );
+
+    const adapter = createInternalIntegrationAdapter({
+      backend: 'bifrost',
+      accessToken: 'token-123',
+      teamId: '11430732',
+      fetchImpl
+    });
+
+    await adapter.syncCollection('spec-123', 'col-1');
+
+    expect(fetchImpl).toHaveBeenCalledWith(
+      'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy',
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({
+          service: 'specification',
+          method: 'post',
+          path: '/specifications/spec-123/collections/col-1/sync'
+        })
+      })
+    );
+  });
+
   it('treats projectAlreadyConnected as idempotent when the same repo is linked', async () => {
     const fetchImpl = vi.fn<typeof fetch>()
       // First call: connectWorkspaceToRepository POST returns 400 projectAlreadyConnected