Design Explicit Homelab Runner Selection

[ptr727]

Objective

Add an explicit fleet runner-selection contract that lets the same workflow definitions use trusted homelab runners or GitHub-hosted Ubuntu runners. Use ptr727/ProjectTemplate as the first real workload after the contract is implemented.

Current platform behavior

runs-on selects one runner target when the job is queued. A label array is cumulative, so a homelab job requires every label:

runs-on: [self-hosted, linux, x64, homelab, ubuntu-24.04]

GitHub does not treat GitHub-hosted and self-hosted labels as alternatives. If no matching self-hosted runner is online, the job remains queued and does not fall back to ubuntu-24.04.

GitHub supports configuration variables and expressions in runs-on. The fleet can therefore select a target explicitly while keeping GitHub-hosted runners as the absent-variable/default case. Do not add an availability probe as an automatic fallback: runner state can change between the probe and scheduling, leaving the selected self-hosted job queued anyway.

Security boundary

ptr727/ProjectTemplate is public. A repository-wide switch must not route arbitrary fork or external-contributor code to a persistent homelab runner.

The selection contract must fail closed:

• absent or invalid configuration selects GitHub-hosted Ubuntu
• untrusted actors and fork pull requests use GitHub-hosted runners or skip the privileged job
• only ptr727, dependabot[bot], and ptr727-codegen[bot] may select the homelab runner
• every self-hosted job preserves the workflow's trusted-trigger checks rather than relying on labels for authorization
• the first hub canary uses a repository-scoped runner registered specifically to ptr727/ProjectTemplate

The current CloudInit runner command refuses public repositories. Supporting the hub requires an explicit, reviewable public-repository opt-in whose workflow guard is part of the same change. Do not silently remove the private-repository safety check.

Copilot code review

Copilot code review uses GitHub Actions for agentic context gathering. Confirm that Copilot reviews continue to arrive when ordinary CI jobs use the homelab runner.

Do not route Copilot code review to the standalone persistent VM. GitHub documents ARC-managed scale sets as the only supported self-hosted solution for Copilot code review and warns against non-ARC self-hosted runners. Keep Copilot review on GitHub-hosted infrastructure for this phase. Evaluate self-hosted Copilot review only with the ephemeral/ARC lifecycle design.

Relevant GitHub documentation:

• https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job
• https://docs.github.com/en/enterprise-cloud@latest/actions/reference/runners/self-hosted-runners
• https://docs.github.com/en/copilot/how-tos/copilot-on-github/set-up-copilot/configure-runners

Design work

• choose a fleet configuration variable name and values, preferring an explicit target over a boolean
• define one canonical expression or reusable-workflow input so repositories do not copy selection logic
• define the trusted-actor and fork behavior for push, pull_request, workflow_dispatch, bot, and scheduled events
• update actionlint custom-label configuration wherever homelab labels appear
• document that selection is explicit and has no automatic offline fallback
• decide how a public-repository opt-in is represented in CloudInit without weakening the private default
• identify which hub jobs are safe and useful as the first homelab canary

Acceptance criteria

• the same workflow sources can select GitHub-hosted Ubuntu or the homelab label set without duplicating job bodies
• missing configuration uses GitHub-hosted Ubuntu
• external pull requests cannot execute on a persistent homelab runner
• trusted hub CI completes on a repository-scoped homelab runner
• a PR using homelab CI still receives a complete Copilot review on GitHub-hosted Copilot infrastructure
• an offline homelab runner produces a visible queued state, documented as no-fallback behavior
• CI covers both selection branches structurally, and the homelab branch is exercised by a live canary

Phase boundary

This issue covers explicit environment selection and the first hub canary. Automatic VM creation, ephemeral runners, fixed-pool reconciliation, and ARC evaluation belong to the phase 2 lifecycle design.

[ptr727]

Implementation planning and private-repository lifecycle experiments are tracked in HomeAutomation-Config #67. The private plan compares persistent, warm ephemeral, per-job ephemeral, and ARC runner models. Keep public hub pull-request jobs and Copilot reviews on GitHub-hosted runners until the selected design provides the required isolation.