@postman-cse/onboarding-bootstrap 0.9.1 → 0.11.0

package/src/index.ts

@@ -1,10 +1,10 @@
 import * as core from '@actions/core';
 import * as exec from '@actions/exec';
 import * as io from '@actions/io';
+import { readFileSync } from 'node:fs';
 import { parse, stringify } from 'yaml';
 
 import { openAlphaActionContract } from './contracts.js';
-import { GitHubApiClient, type GitHubApiClientAuthMode } from './lib/github/github-api-client.js';
 import { createInternalIntegrationAdapter, type InternalIntegrationAdapter } from './lib/postman/internal-integration-adapter.js';
 import { PostmanAssetsClient } from './lib/postman/postman-assets-client.js';
 import { resolveCanonicalWorkspaceSelection } from './lib/postman/workspace-selection.js';
@@ -19,22 +19,26 @@ export interface ResolvedInputs {
   baselineCollectionId?: string;
   smokeCollectionId?: string;
   contractCollectionId?: string;
+  syncExamples: boolean;
+  collectionSyncMode: 'reuse' | 'refresh' | 'version';
+  specSyncMode: 'update' | 'version';
+  releaseLabel?: string;
   domain?: string;
   domainCode?: string;
   requesterEmail?: string;
   workspaceAdminUserIds?: string;
+  workspaceTeamId?: string;
   teamId?: string;
   repoUrl?: string;
   specUrl: string;
-  environmentsJson: string;
-  systemEnvMapJson: string;
   governanceMappingJson: string;
   postmanApiKey: string;
   postmanAccessToken?: string;
-  githubToken?: string;
-  ghFallbackToken?: string;
-  githubAuthMode: string;
   integrationBackend: string;
+  githubRefName?: string;
+  githubHeadRef?: string;
+  githubRef?: string;
+  githubSha?: string;
 }
 
 export interface PlannedOutputs {
@@ -61,13 +65,6 @@ export interface LintSummary {
   warnings: number;
 }
 
-interface BootstrapRepositoryVariables {
-  lintErrors: number;
-  lintWarnings: number;
-}
-
-type RepoVariableClient = Pick<GitHubApiClient, 'setRepositoryVariable' | 'getRepositoryVariable'>;
-
 export interface CoreLike {
   error(message: string): void;
   getInput(name: string, options?: { required?: boolean }): string;
@@ -102,11 +99,10 @@ export interface BootstrapExecutionDependencies {
     'error' | 'group' | 'info' | 'setOutput' | 'warning'
   >;
   exec: ExecLike;
-  github?: RepoVariableClient;
   io: IOLike;
   internalIntegration?: Pick<
     InternalIntegrationAdapter,
-    'assignWorkspaceToGovernanceGroup'
+    'assignWorkspaceToGovernanceGroup' | 'linkCollectionsToSpecification' | 'syncCollection'
   >;
   postman: Pick<
     PostmanAssetsClient,
@@ -116,6 +112,7 @@ export interface BootstrapExecutionDependencies {
     | 'generateCollection'
     | 'getAutoDerivedTeamId'
     | 'getSpecContent'
+    | 'getTeams'
     | 'getWorkspaceGitRepoUrl'
     | 'injectTests'
     | 'inviteRequesterToWorkspace'
@@ -185,16 +182,28 @@ function asStringArray(value: unknown, inputName: string): string[] {
   return value.map((entry) => String(entry));
 }
 
-function asStringMap(value: unknown, inputName: string): Record<string, string> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${inputName} must be a JSON object`);
+function parseBooleanInput(value: string | undefined, defaultValue: boolean): boolean {
+  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: string | undefined
+): 'reuse' | 'refresh' | 'version' {
+  if (value === 'reuse' || value === 'version') {
+    return value;
   }
-  return Object.fromEntries(
-    Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
-      key,
-      String(entry)
-    ])
-  );
+  return 'refresh';
+}
+
+function parseSpecSyncMode(value: string | undefined): 'update' | 'version' {
+  if (value === 'version') {
+    return value;
+  }
+  return 'update';
 }
 
 export function resolveInputs(
@@ -233,41 +242,39 @@ export function resolveInputs(
   }
 
   return {
-    projectName: getInput('project-name', env) ?? '',
+    projectName: getInput('project-name', env)
+      ?? env.GITHUB_REPOSITORY?.split('/').pop()
+      ?? env.CI_PROJECT_NAME
+      ?? '',
     workspaceId: getInput('workspace-id', env),
     specId: getInput('spec-id', 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),
     domain: getInput('domain', env),
     domainCode: getInput('domain-code', env),
     requesterEmail: getInput('requester-email', env),
     workspaceAdminUserIds:
       getInput('workspace-admin-user-ids', env) || env.WORKSPACE_ADMIN_USER_IDS || '',
+    workspaceTeamId: getInput('workspace-team-id', env) || env.POSTMAN_WORKSPACE_TEAM_ID,
     teamId: getInput('team-id', env) || env.POSTMAN_TEAM_ID || '',
     repoUrl: repoContext.repoUrl || '',
     specUrl,
-    environmentsJson:
-      getInput('environments-json', env) ??
-      openAlphaActionContract.inputs['environments-json'].default ??
-      '["prod"]',
-    systemEnvMapJson:
-      getInput('system-env-map-json', env) ??
-      openAlphaActionContract.inputs['system-env-map-json'].default ??
-      '{}',
     governanceMappingJson:
       getInput('governance-mapping-json', env) ??
       openAlphaActionContract.inputs['governance-mapping-json'].default ??
       '{}',
     postmanApiKey: getInput('postman-api-key', env) ?? '',
     postmanAccessToken: getInput('postman-access-token', env),
-    githubToken: getInput('github-token', env),
-    ghFallbackToken: getInput('gh-fallback-token', env),
-    githubAuthMode:
-      getInput('github-auth-mode', env) ??
-      openAlphaActionContract.inputs['github-auth-mode'].default ??
-      'github_token_first',
-    integrationBackend
+    integrationBackend,
+    githubRefName: env.GITHUB_REF_NAME,
+    githubHeadRef: env.GITHUB_HEAD_REF,
+    githubRef: env.GITHUB_REF,
+    githubSha: env.GITHUB_SHA
   };
 }
 
@@ -305,13 +312,9 @@ export function readActionInputs(
   const specUrl = requireInput(actionCore, 'spec-url');
   const postmanApiKey = requireInput(actionCore, 'postman-api-key');
   const postmanAccessToken = optionalInput(actionCore, 'postman-access-token');
-  const githubToken = optionalInput(actionCore, 'github-token');
-  const ghFallbackToken = optionalInput(actionCore, 'gh-fallback-token');
 
   actionCore.setSecret(postmanApiKey);
   if (postmanAccessToken) actionCore.setSecret(postmanAccessToken);
-  if (githubToken) actionCore.setSecret(githubToken);
-  if (ghFallbackToken) actionCore.setSecret(ghFallbackToken);
 
   const inputs = resolveInputs({
     ...process.env,
@@ -321,6 +324,16 @@ 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,
+    INPUT_SPEC_SYNC_MODE:
+      optionalInput(actionCore, 'spec-sync-mode') ??
+      openAlphaActionContract.inputs['spec-sync-mode'].default,
+    INPUT_RELEASE_LABEL: optionalInput(actionCore, 'release-label'),
     INPUT_DOMAIN: optionalInput(actionCore, 'domain'),
     INPUT_DOMAIN_CODE: optionalInput(actionCore, 'domain-code'),
     INPUT_REQUESTER_EMAIL: optionalInput(actionCore, 'requester-email'),
@@ -328,26 +341,17 @@ export function readActionInputs(
       actionCore,
       'workspace-admin-user-ids'
     ),
+    INPUT_WORKSPACE_TEAM_ID:
+      optionalInput(actionCore, 'workspace-team-id') || process.env.POSTMAN_WORKSPACE_TEAM_ID,
     INPUT_TEAM_ID:
       optionalInput(actionCore, 'postman-team-id') || process.env.POSTMAN_TEAM_ID,
     INPUT_REPO_URL: optionalInput(actionCore, 'repo-url'),
     INPUT_SPEC_URL: specUrl,
-    INPUT_ENVIRONMENTS_JSON:
-      optionalInput(actionCore, 'environments-json') ??
-      openAlphaActionContract.inputs['environments-json'].default,
-    INPUT_SYSTEM_ENV_MAP_JSON:
-      optionalInput(actionCore, 'system-env-map-json') ??
-      openAlphaActionContract.inputs['system-env-map-json'].default,
     INPUT_GOVERNANCE_MAPPING_JSON:
       optionalInput(actionCore, 'governance-mapping-json') ??
       openAlphaActionContract.inputs['governance-mapping-json'].default,
     INPUT_POSTMAN_API_KEY: postmanApiKey,
     INPUT_POSTMAN_ACCESS_TOKEN: postmanAccessToken,
-    INPUT_GITHUB_TOKEN: githubToken,
-    INPUT_GH_FALLBACK_TOKEN: ghFallbackToken,
-    INPUT_GITHUB_AUTH_MODE:
-      optionalInput(actionCore, 'github-auth-mode') ??
-      openAlphaActionContract.inputs['github-auth-mode'].default,
     INPUT_INTEGRATION_BACKEND:
       optionalInput(actionCore, 'integration-backend') ??
       openAlphaActionContract.inputs['integration-backend'].default
@@ -456,6 +460,83 @@ async function fetchSpecDocument(
   );
 }
 
+function normalizeReleaseLabel(value: string | undefined): string | undefined {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  return trimmed
+    .replace(/^refs\/heads\//, '')
+    .replace(/^refs\/tags\//, '')
+    .replace(/^refs\/pull\//, 'pull-')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || undefined;
+}
+
+function deriveReleaseLabel(inputs: ResolvedInputs): string | undefined {
+  if (inputs.releaseLabel) {
+    return normalizeReleaseLabel(inputs.releaseLabel);
+  }
+
+  return (
+    normalizeReleaseLabel(inputs.githubRefName) ??
+    normalizeReleaseLabel(inputs.githubHeadRef) ??
+    normalizeReleaseLabel(inputs.githubRef)
+  );
+}
+
+function createAssetProjectName(
+  inputs: ResolvedInputs,
+  releaseLabel?: string
+): string {
+  if (!releaseLabel) {
+    return inputs.projectName;
+  }
+
+  return `${inputs.projectName} ${releaseLabel}`;
+}
+
+type CloudResourceMap = Record<string, string>;
+
+type PostmanResourcesState = {
+  workspace?: {
+    id?: string;
+  };
+  cloudResources?: {
+    collections?: CloudResourceMap;
+    environments?: CloudResourceMap;
+    specs?: CloudResourceMap;
+  };
+};
+
+function readResourcesState(): PostmanResourcesState | null {
+  try {
+    return parse(readFileSync('.postman/resources.yaml', 'utf8')) as PostmanResourcesState;
+  } catch {
+    return null;
+  }
+}
+
+function getFirstCloudResourceId(map: CloudResourceMap | undefined): string | undefined {
+  if (!map) {
+    return undefined;
+  }
+  return Object.values(map)[0];
+}
+
+function findCloudResourceId(
+  map: CloudResourceMap | undefined,
+  matcher: (path: string) => boolean
+): string | undefined {
+  if (!map) {
+    return undefined;
+  }
+
+  const match = Object.entries(map).find(([filePath]) => matcher(filePath));
+  return match?.[1];
+}
+
 const SPEC_SUMMARY_MAX_LEN = 200;
 const SPEC_HTTP_METHODS = new Set([
   'get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'
@@ -542,146 +623,19 @@ function validateSpecStructure(content: string): void {
   }
 }
 
-function varName(projectName: string, baseName: string): string {
-  const slug = projectName.toUpperCase().replace(/[^A-Z0-9]/g, '_');
-  return `POSTMAN_${slug}_${baseName}`;
-}
-
-async function readVariable(
-  github: RepoVariableClient | undefined,
-  projectName: string,
-  baseName: string
-): Promise<string | undefined> {
-  if (!github) {
-    return undefined;
-  }
-
-  const namespaced = await github
-    .getRepositoryVariable(varName(projectName, baseName))
-    .catch(() => undefined);
-  if (namespaced) {
-    return namespaced;
-  }
-
-  const legacy = await github
-    .getRepositoryVariable(`POSTMAN_${baseName}`)
-    .catch(() => undefined);
-  return legacy || undefined;
-}
-
-async function persistVariable(
-  github: RepoVariableClient | undefined,
-  name: string,
-  value: string,
-  actionCore: Pick<CoreLike, 'warning'>
-): Promise<void> {
-  if (!github || !value) {
-    return;
-  }
-
-  try {
-    await github.setRepositoryVariable(name, value);
-  } catch (err) {
-    actionCore.warning(
-      `Failed to persist ${name}: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-
-async function writeVariable(
-  github: RepoVariableClient | undefined,
-  projectName: string,
-  baseName: string,
-  value: string,
-  actionCore: Pick<CoreLike, 'warning'>
-): Promise<void> {
-  if (!github || !value) {
-    return;
-  }
-
-  await persistVariable(github, varName(projectName, baseName), value, actionCore);
-  await persistVariable(github, `POSTMAN_${baseName}`, value, actionCore);
-}
-
-async function persistBootstrapRepositoryVariables(
-  github: RepoVariableClient,
-  projectName: string,
-  outputs: PlannedOutputs,
-  systemEnvMap: Record<string, string>,
-  environments: string[],
-  lintSummary: BootstrapRepositoryVariables,
-  actionCore: Pick<CoreLike, 'warning'>
-): Promise<void> {
-  await persistVariable(
-    github,
-    'LINT_WARNINGS',
-    String(lintSummary.lintWarnings),
-    actionCore
-  );
-  await persistVariable(
-    github,
-    'LINT_ERRORS',
-    String(lintSummary.lintErrors),
-    actionCore
-  );
-  await writeVariable(
-    github,
-    projectName,
-    'WORKSPACE_ID',
-    outputs['workspace-id'],
-    actionCore
-  );
-  await writeVariable(github, projectName, 'SPEC_UID', outputs['spec-id'], actionCore);
-  await writeVariable(
-    github,
-    projectName,
-    'BASELINE_COLLECTION_UID',
-    outputs['baseline-collection-id'],
-    actionCore
-  );
-  await writeVariable(
-    github,
-    projectName,
-    'SMOKE_COLLECTION_UID',
-    outputs['smoke-collection-id'],
-    actionCore
-  );
-  await writeVariable(
-    github,
-    projectName,
-    'CONTRACT_COLLECTION_UID',
-    outputs['contract-collection-id'],
-    actionCore
-  );
-
-  for (const envName of environments) {
-    const systemEnvId = systemEnvMap[envName];
-    if (!systemEnvId) {
-      continue;
-    }
-    await writeVariable(
-      github,
-      projectName,
-      `SYSTEM_ENV_${envName.toUpperCase()}`,
-      systemEnvId,
-      actionCore
-    );
-  }
-}
-
 export async function runBootstrap(
   inputs: ResolvedInputs,
   dependencies: BootstrapExecutionDependencies
 ): Promise<PlannedOutputs> {
   const outputs = createPlannedOutputs(inputs);
-  const environments = asStringArray(
-    parseJsonValue(inputs.environmentsJson, ['prod'], 'environments-json'),
-    'environments-json'
-  );
-  const systemEnvMap = asStringMap(
-    parseJsonValue(inputs.systemEnvMapJson, {}, 'system-env-map-json'),
-    'system-env-map-json'
-  );
+  const requiresReleaseLabel =
+    inputs.collectionSyncMode === 'version' || inputs.specSyncMode === 'version';
+  const releaseLabel = requiresReleaseLabel ? deriveReleaseLabel(inputs) : undefined;
+  if (requiresReleaseLabel && !releaseLabel) {
+    throw new Error(
+      'Versioned spec or collection sync requires a release-label or derivable GitHub ref metadata'
+    );
+  }
   const workspaceName = createWorkspaceName(inputs);
   const aboutText = `Auto-provisioned by Postman CS open-alpha for ${inputs.projectName}`;
 
@@ -689,19 +643,17 @@ export async function runBootstrap(
     await ensurePostmanCli(dependencies, inputs.postmanApiKey);
   });
 
+  const resourcesState = readResourcesState();
 
-  const explicitWorkspaceId = inputs.workspaceId;
-  let repoWorkspaceId: string | undefined;
-  let workspaceId = explicitWorkspaceId;
-  if (!workspaceId && dependencies.github) {
-    repoWorkspaceId = await readVariable(
-      dependencies.github,
-      inputs.projectName,
-      'WORKSPACE_ID'
-    );
-    workspaceId = repoWorkspaceId;
+  let explicitWorkspaceId = inputs.workspaceId;
+  if (!explicitWorkspaceId && resourcesState?.workspace?.id) {
+    explicitWorkspaceId = resourcesState.workspace.id;
+    dependencies.core.info('Resolved workspace-id from .postman/resources.yaml');
   }
 
+  const repoWorkspaceId = explicitWorkspaceId;
+  let workspaceId = explicitWorkspaceId;
+
   let teamId = inputs.teamId || '';
   if (!teamId) {
     teamId = await dependencies.postman.getAutoDerivedTeamId() || '';
@@ -738,11 +690,66 @@ export async function runBootstrap(
     dependencies.core.info(`Using existing workspace: ${workspaceId}`);
   }
 
+  // Parse workspace-team-id from already-resolved inputs
+  let workspaceTeamId: number | undefined;
+  if (inputs.workspaceTeamId) {
+    workspaceTeamId = parseInt(inputs.workspaceTeamId, 10);
+    if (Number.isNaN(workspaceTeamId)) {
+      throw new Error(`workspace-team-id must be a numeric sub-team ID, got: ${inputs.workspaceTeamId}`);
+    }
+  }
+
+  // Org-mode detection: only check if we need to create a workspace (not reuse existing)
+  if (!workspaceId && !workspaceTeamId) {
+    try {
+      const teams = await dependencies.postman.getTeams();
+      if (teams.length > 1 && teams.every(t => t.organizationId == null)) {
+        dependencies.core.warning(
+          'GET /teams returned multiple teams but none include organizationId. ' +
+          'Org-mode detection may be degraded due to an upstream API change. ' +
+          'If workspace creation fails, set workspace-team-id explicitly.'
+        );
+      }
+      const orgIds = new Set(teams.filter(t => t.organizationId != null).map(t => t.organizationId));
+      const meTeamId = parseInt(teamId, 10);
+      const isOrgMode = teams.length > 1
+        && orgIds.size === 1
+        && orgIds.has(meTeamId);
+
+      if (isOrgMode) {
+        const teamList = teams
+          .map(t => `  ${t.id}  ${t.name}`)
+          .join('\n');
+        throw new Error(
+          `Org-mode account detected. Workspace creation requires a specific sub-team ID.\n\n` +
+          `Available sub-teams:\n${teamList}\n\n` +
+          `To fix this, set the workspace-team-id input in your workflow:\n` +
+          `  workspace-team-id: '<id>'\n\n` +
+          `Or for reuse across runs, create a repository variable and reference it:\n` +
+          `  workspace-team-id: \${{ vars.POSTMAN_WORKSPACE_TEAM_ID }}\n\n` +
+          `For CLI usage, pass --workspace-team-id <id> or export POSTMAN_WORKSPACE_TEAM_ID=<id>.`
+        );
+      } else if (teams.length > 1) {
+        dependencies.core.warning(
+          `API key has access to ${teams.length} teams but org-mode could not be confirmed. ` +
+          `Proceeding without teamId. If workspace creation fails, set workspace-team-id explicitly.`
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes('Org-mode account detected')) {
+        throw err;
+      }
+      dependencies.core.warning(
+        `Could not check for org-mode sub-teams: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
   if (!workspaceId) {
     const workspace = await runGroup(
       dependencies.core,
       'Create Postman Workspace',
-      async () => dependencies.postman.createWorkspace(workspaceName, aboutText)
+      async () => dependencies.postman.createWorkspace(workspaceName, aboutText, workspaceTeamId)
     );
     workspaceId = workspace.id;
   }
@@ -750,14 +757,6 @@ export async function runBootstrap(
   outputs['workspace-id'] = workspaceId || '';
   outputs['workspace-url'] = `https://go.postman.co/workspace/${workspaceId}`;
   outputs['workspace-name'] = workspaceName;
-  await writeVariable(
-    dependencies.github,
-    inputs.projectName,
-    'WORKSPACE_ID',
-    outputs['workspace-id'],
-    dependencies.core
-  );
-
 
   if (inputs.domain && dependencies.internalIntegration) {
     await runGroup(
@@ -818,37 +817,49 @@ export async function runBootstrap(
     );
   }
 
-
   let specId = inputs.specId;
-  if (!specId && dependencies.github) {
-    specId = await readVariable(dependencies.github, inputs.projectName, 'SPEC_UID');
+  if (!specId) {
+    specId = getFirstCloudResourceId(resourcesState?.cloudResources?.specs);
+    if (specId) {
+      dependencies.core.info('Resolved spec-id from .postman/resources.yaml');
+    }
   }
 
-  let baselineCollectionId = inputs.baselineCollectionId;
-  let smokeCollectionId = inputs.smokeCollectionId;
-  let contractCollectionId = inputs.contractCollectionId;
+  let baselineCollectionId =
+    inputs.collectionSyncMode === 'refresh' ? undefined : inputs.baselineCollectionId;
+  let smokeCollectionId =
+    inputs.collectionSyncMode === 'refresh' ? undefined : inputs.smokeCollectionId;
+  let contractCollectionId =
+    inputs.collectionSyncMode === 'refresh' ? undefined : inputs.contractCollectionId;
 
-  if (dependencies.github) {
+  if (inputs.collectionSyncMode !== 'refresh') {
+    const cloudCollections = resourcesState?.cloudResources?.collections;
     if (!baselineCollectionId) {
-      baselineCollectionId = await readVariable(
-        dependencies.github,
-        inputs.projectName,
-        'BASELINE_COLLECTION_UID'
+      baselineCollectionId = findCloudResourceId(
+        cloudCollections,
+        (filePath) => filePath.includes('[Baseline]')
       );
+      if (baselineCollectionId) {
+        dependencies.core.info('Resolved baseline-collection-id from .postman/resources.yaml');
+      }
     }
     if (!smokeCollectionId) {
-      smokeCollectionId = await readVariable(
-        dependencies.github,
-        inputs.projectName,
-        'SMOKE_COLLECTION_UID'
+      smokeCollectionId = findCloudResourceId(
+        cloudCollections,
+        (filePath) => filePath.includes('[Smoke]')
       );
+      if (smokeCollectionId) {
+        dependencies.core.info('Resolved smoke-collection-id from .postman/resources.yaml');
+      }
     }
     if (!contractCollectionId) {
-      contractCollectionId = await readVariable(
-        dependencies.github,
-        inputs.projectName,
-        'CONTRACT_COLLECTION_UID'
+      contractCollectionId = findCloudResourceId(
+        cloudCollections,
+        (filePath) => filePath.includes('[Contract]')
       );
+      if (contractCollectionId) {
+        dependencies.core.info('Resolved contract-collection-id from .postman/resources.yaml');
+      }
     }
   }
 
@@ -874,7 +885,10 @@ export async function runBootstrap(
       } else {
         specId = await dependencies.postman.uploadSpec(
           workspaceId || '',
-          inputs.projectName,
+          createAssetProjectName(
+            inputs,
+            inputs.specSyncMode === 'version' ? releaseLabel : undefined
+          ),
           document
         );
       }
@@ -884,13 +898,6 @@ export async function runBootstrap(
   );
 
   void specContent;
-  await writeVariable(
-    dependencies.github,
-    inputs.projectName,
-    'SPEC_UID',
-    outputs['spec-id'],
-    dependencies.core
-  );
 
   const lintSummary = await runGroup(
     dependencies.core,
@@ -936,14 +943,23 @@ export async function runBootstrap(
     dependencies.core,
     'Generate Collections from Spec',
     async () => {
-      outputs['baseline-collection-id'] = baselineCollectionId || '';
-      outputs['smoke-collection-id'] = smokeCollectionId || '';
-      outputs['contract-collection-id'] = contractCollectionId || '';
+      const shouldReuseCollections = inputs.collectionSyncMode !== 'refresh';
+      const assetProjectName =
+        inputs.collectionSyncMode === 'version'
+          ? createAssetProjectName(inputs, releaseLabel)
+          : inputs.projectName;
+
+      outputs['baseline-collection-id'] =
+        shouldReuseCollections ? baselineCollectionId || '' : '';
+      outputs['smoke-collection-id'] =
+        shouldReuseCollections ? smokeCollectionId || '' : '';
+      outputs['contract-collection-id'] =
+        shouldReuseCollections ? contractCollectionId || '' : '';
 
       if (!outputs['baseline-collection-id']) {
         outputs['baseline-collection-id'] = await dependencies.postman.generateCollection(
           outputs['spec-id'],
-          inputs.projectName,
+          assetProjectName,
           '[Baseline]'
         );
       } else {
@@ -951,18 +967,10 @@ export async function runBootstrap(
           `Using existing baseline collection: ${outputs['baseline-collection-id']}`
         );
       }
-      await writeVariable(
-        dependencies.github,
-        inputs.projectName,
-        'BASELINE_COLLECTION_UID',
-        outputs['baseline-collection-id'],
-        dependencies.core
-      );
-
       if (!outputs['smoke-collection-id']) {
         outputs['smoke-collection-id'] = await dependencies.postman.generateCollection(
           outputs['spec-id'],
-          inputs.projectName,
+          assetProjectName,
           '[Smoke]'
         );
       } else {
@@ -970,18 +978,10 @@ export async function runBootstrap(
           `Using existing smoke collection: ${outputs['smoke-collection-id']}`
         );
       }
-      await writeVariable(
-        dependencies.github,
-        inputs.projectName,
-        'SMOKE_COLLECTION_UID',
-        outputs['smoke-collection-id'],
-        dependencies.core
-      );
-
       if (!outputs['contract-collection-id']) {
         outputs['contract-collection-id'] = await dependencies.postman.generateCollection(
           outputs['spec-id'],
-          inputs.projectName,
+          assetProjectName,
           '[Contract]'
         );
       } else {
@@ -989,13 +989,6 @@ export async function runBootstrap(
           `Using existing contract collection: ${outputs['contract-collection-id']}`
         );
       }
-      await writeVariable(
-        dependencies.github,
-        inputs.projectName,
-        'CONTRACT_COLLECTION_UID',
-        outputs['contract-collection-id'],
-        dependencies.core
-      );
     }
   );
 
@@ -1037,26 +1030,49 @@ export async function runBootstrap(
     }
   );
 
-  if (dependencies.github) {
-    const github = dependencies.github;
-    await runGroup(
-      dependencies.core,
-      'Store Postman UIDs as Repo Variables',
-      async () => {
-        await persistBootstrapRepositoryVariables(
-          github,
-          inputs.projectName,
-          outputs,
-          systemEnvMap,
-          environments,
-          {
-            lintErrors: lintSummary.errors,
-            lintWarnings: lintSummary.warnings
-          },
-          dependencies.core
-        );
-      }
-    );
+  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)) {
@@ -1079,9 +1095,6 @@ export async function runAction(
     specFetcher: fetch
   });
 
-  if (!dependencies.github) {
-    actionCore.info('GitHub repository variable persistence disabled for this run');
-  }
   if (inputs.domain && !dependencies.internalIntegration) {
     actionCore.warning(
       'Skipping governance assignment because postman-access-token is not configured'
@@ -1097,25 +1110,12 @@ export function createBootstrapDependencies(
 ): BootstrapExecutionDependencies {
   const secretMasker = createSecretMasker([
     inputs.postmanApiKey,
-    inputs.postmanAccessToken,
-    inputs.githubToken,
-    inputs.ghFallbackToken
+    inputs.postmanAccessToken
   ]);
   const postman = new PostmanAssetsClient({
     apiKey: inputs.postmanApiKey,
     secretMasker
   });
-  const repository = extractRepositorySlug(inputs.repoUrl);
-  const github =
-    inputs.githubToken && inputs.repoUrl && repository
-      ? new GitHubApiClient({
-        authMode: inputs.githubAuthMode as GitHubApiClientAuthMode,
-        fallbackToken: inputs.ghFallbackToken,
-        repository,
-        secretMasker,
-        token: inputs.githubToken
-      })
-      : undefined;
   const internalIntegration =
     inputs.postmanAccessToken
       ? createInternalIntegrationAdapter({
@@ -1129,7 +1129,6 @@ export function createBootstrapDependencies(
   return {
     core: factories.core,
     exec: factories.exec,
-    github,
     io: factories.io,
     internalIntegration,
     postman,
@@ -1137,25 +1136,6 @@ export function createBootstrapDependencies(
   };
 }
 
-export function extractRepositorySlug(repoUrl: string | undefined): string | undefined {
-  const normalized = normalizeInputValue(repoUrl);
-  if (!normalized) {
-    return undefined;
-  }
-
-  try {
-    const parsed = new URL(normalized);
-    const pathname = parsed.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '');
-    const segments = pathname.split('/').filter(Boolean);
-    if (segments.length >= 2) {
-      return `${segments[0]}/${segments[1]}`;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 const currentModulePath = typeof __filename === 'string' ? __filename : '';
 const entrypoint = process.argv[1];