What

Create a shared, reusable GitHub Actions composite action that standardizes vcpkg bootstrap, version pinning, and caching across all kcenon ecosystem CI workflows.

Current CI Patterns (3 different approaches)

Key Problems

1. Pattern A clones vcpkg from HEAD — the resolved vcpkg commit drifts from the declared baseline (d90a9b159c... in vcpkg-configuration.json), breaking reproducibility
2. Each repo duplicates 15-30 lines of vcpkg setup logic (clone, bootstrap, cache keys, toolchain path)
3. Cache key strategies differ — some hash vcpkg.json only, others hash vcpkg.json + vcpkg-configuration.json
4. Only monitoring_system pins vcpkg to the baseline commit (in validate-vcpkg-chain.yml using lukka/run-vcpkg@v11)

Why

• Non-reproducible builds: Two CI runs on the same commit can produce different results if microsoft/vcpkg main branch changes between them
• Maintenance cost: A vcpkg cache key bug must be fixed in 6+ repos individually
• Inconsistent behavior: Some repos use vcpkg install --x-manifest-root=., others rely on CMake's VCPKG_MANIFEST_MODE
• Onboarding friction: New ecosystem repos must copy-paste and adapt CI setup from existing repos

Where

Proposed Location

Host the composite action in kcenon/common_system (Tier 0 foundation), referenced by other repos as:

- uses: kcenon/common_system/.github/actions/setup-vcpkg@main

How

Technical Approach

1. Create composite action with these inputs:

name: 'Setup vcpkg'
description: 'Bootstrap vcpkg pinned to ecosystem baseline with caching'
inputs:
  vcpkg-commit:
    description: 'vcpkg commit to checkout (default: ecosystem baseline)'
    required: false
    default: 'd90a9b159c08169f39adcd1b0f1ac0ca12c4b96c'
  manifest-dir:
    description: 'Directory containing vcpkg.json'
    required: false
    default: '.'
  extra-cache-key:
    description: 'Additional cache key suffix for project-specific differentiation'
    required: false
    default: ''

2. Action steps:

   • Checkout microsoft/vcpkg at the pinned commit
   • Bootstrap vcpkg (bootstrap-vcpkg.sh / bootstrap-vcpkg.bat)
   • Set VCPKG_ROOT and CMAKE_TOOLCHAIN_FILE environment variables
   • Configure GitHub Actions cache with key: vcpkg-{os}-{hash(vcpkg.json, vcpkg-configuration.json)}-{extra-cache-key}

3. Outputs:

   • vcpkg-root: Path to vcpkg installation
   • toolchain-file: Path to vcpkg.cmake

Rollout Plan

Acceptance Criteria

• Composite action created at .github/actions/setup-vcpkg/action.yml
• vcpkg checkout pinned to ecosystem baseline commit by default
• Cache key includes both vcpkg.json and vcpkg-configuration.json hashes
• Works on Ubuntu, macOS, and Windows runners
• At least one ecosystem project's CI workflow migrated to use the action
• README with usage examples and input documentation
• Action output provides VCPKG_ROOT and CMAKE_TOOLCHAIN_FILE

Related

• Part of chore(vcpkg): standardize vcpkg configuration across satellite projects #509
• Reference: monitoring_system's validate-vcpkg-chain.yml (already pins vcpkg via lukka/run-vcpkg@v11)