What

Automate the synchronization of vcpkg port files from each source repository to the central kcenon/vcpkg-registry upon release. Currently, this is a manual process requiring a maintainer to copy portfiles and update version databases after every release across all 8 ecosystem systems.

• Current: When a system releases a new version (e.g., common_system v0.2.0), a maintainer must manually:
  1. Copy the updated vcpkg-ports/kcenon-<system>/ to vcpkg-registry/ports/kcenon-<system>/
  2. Update vcpkg-registry/versions/k-/kcenon-<system>.json with the new version entry
  3. Update vcpkg-registry/versions/baseline.json with the new version
  4. Commit and push to the registry
• Expected: A reusable GitHub Actions workflow that, on release tag creation, automatically opens a PR to kcenon/vcpkg-registry with the updated portfiles and version database entries.
• Scope: .github/workflows/sync-vcpkg-registry.yml in monitoring_system (reusable), adopted by all 8 systems

Why

Error-prone manual process

• 8 systems × 4 manual steps = 32 manual operations per full ecosystem release
• Missing or incorrect version database entries cause vcpkg install resolution failures
• SHA512 hash mismatches between portfile and actual release archive are common copy-paste errors

Delayed availability

• After a release is tagged, consumers cannot use the new version via vcpkg install until the registry is manually updated — this delay ranges from hours to days depending on maintainer availability.

Single point of failure

• Only maintainers with write access to vcpkg-registry can perform the sync. If unavailable, the entire ecosystem's vcpkg availability stalls.

Ecosystem precedent

• monitoring_system already serves as the canonical source of truth for all 8 ecosystem ports (vcpkg-ports/ directory). This workflow formalizes that role with automation.

Where

New workflow (reusable)

Caller workflows (one per system)

Each ecosystem repository adds a caller workflow:

How

Technical Approach

Reusable Workflow Design

name: Sync vcpkg Registry

on:
  workflow_call:
    inputs:
      port-name:
        description: 'vcpkg port name (e.g., kcenon-common-system)'
        required: true
        type: string
      version:
        description: 'Release version (e.g., 0.2.0)'
        required: true
        type: string
    secrets:
      REGISTRY_PAT:
        description: 'PAT with write access to kcenon/vcpkg-registry'
        required: true

Workflow Steps

1. Checkout source repo — access the vcpkg-ports/<port-name>/ directory
2. Download release archive — compute SHA512 hash of the actual release tarball
3. Update portfile.cmake — replace SHA512 hash and verify REF tag matches version
4. Checkout vcpkg-registry — clone kcenon/vcpkg-registry
5. Copy port files — overwrite ports/<port-name>/ with updated portfile and vcpkg.json
6. Update version database:
   • versions/<prefix>/<port-name>.json — append new version entry with git-tree SHA
   • versions/baseline.json — update baseline version and port-version
7. Create PR — open a PR to vcpkg-registry with title [bot] Update <port-name> to v<version>
8. Validate — run vcpkg install <port-name> in the PR CI to verify the port works

Caller Workflow (per system)

name: Sync vcpkg Registry

on:
  release:
    types: [published]

jobs:
  sync:
    uses: kcenon/monitoring_system/.github/workflows/sync-vcpkg-registry.yml@main
    with:
      port-name: kcenon-<system-name>
      version: ${{ github.event.release.tag_name }}
    secrets:
      REGISTRY_PAT: ${{ secrets.VCPKG_REGISTRY_PAT }}

SHA512 Hash Computation

# Download release archive and compute hash
curl -sL "https://github.com/kcenon/${REPO}/archive/refs/tags/v${VERSION}.tar.gz" \
  | sha512sum | awk '{print $1}'

Version Database Update

# versions/k-/kcenon-<port>.json — append entry
{
  "versions": [
    {
      "version": "<new-version>",
      "port-version": 0,
      "git-tree": "<computed-git-tree-sha>"
    },
    ... // existing entries
  ]
}

Security Considerations

• Use a fine-grained PAT with write access scoped to kcenon/vcpkg-registry only
• Store as VCPKG_REGISTRY_PAT organization secret (shared across ecosystem repos)
• PR-based approach (not direct push) allows human review before merge
• SHA512 hash verification prevents supply-chain attacks via tampered archives

Rollout Plan

1. Phase 1: Implement reusable workflow in monitoring_system, test with monitoring_system release
2. Phase 2: Add caller workflows to common_system and thread_system (Tier 0-1, most frequently released)
3. Phase 3: Roll out to remaining 5 systems

Acceptance Criteria

• Reusable workflow created in monitoring_system
• On release tag creation, PR is automatically opened to vcpkg-registry
• PR includes updated portfile with correct SHA512 hash
• PR includes updated version database entries
• vcpkg install succeeds in PR validation CI
• Manual approval still required before registry PR merge (safety gate)
• Documentation in docs/guides/PORT_MANAGEMENT.md updated to describe automated flow

Related

• docs/guides/PORT_MANAGEMENT.md — current manual port update procedure
• vcpkg-ports/ — canonical source of all 8 ecosystem portfiles
• validate-vcpkg-chain.yml — validates portfiles work end-to-end