Skip to content

0046: Move the code and the pipeline to GitHub ​

Decided 2026-11-06. Decided by: Product Owner.

Context ​

The code, issues, pull requests and CI lived on a self-hosted git host that was retired on 2026-11-06, with two runners on the Mac mini. Three things made that costly:

  • DH-13 / P1 was open. Production secrets (DOPPLER_TOKEN_PRD, and the migration token DOPPLER_TOKEN) sat in the deploy runner's own environment. Any branch could name that runner in its own copy of the workflow and read them (#71). That host had no way to restrict a runner or a secret to main, so the plan's answer was #71 stage 2: a pull-based deploy agent and builder outside its Actions. That is a lot of new infrastructure, and slice 1 of the deploy-hardening plan waits on it.
  • The SGE plugin speaks GitHub. On the old host it needed a project skill, host overrides in .claude/settings.json and an extra MCP server, and some steps had no equivalent.
  • Operations. The old host's API could not re-run jobs, the UI Re-run had returned a 500, and a Mac mini that is off stopped every check, the deploy and the 15-minute health monitor.

On 2026-11-06 the repository was pushed, with its full history and the same issue numbers, to GitHub as FEAW-Serv/getmy-books (private).

Decision ​

  1. GitHub is the git host. origin is https://github.com/FEAW-Serv/getmy-books.git. Issues and pull requests use gh; the SGE plugin runs natively.
  2. One pipeline, .github/workflows/. ci.yml, health.yml, performance.yml and renovate.yml are ported with every job's behaviour kept. Each job reports as a check on the commit.
  3. Runners. Jobs that need nothing on the LAN run on GitHub's ubuntu-latest: verify, security, n1-compat, build-image, smoke-nas (it checks through the public tunnel), deploy-docs (Cloudflare), alert-main-failed (ntfy), Health and Performance. Jobs that must reach the NAS on the LAN, migrate-nas and deploy-nas, run on [self-hosted, getmy-books-deploy]: one repository-scoped runner on the Mac mini. Health moving off the Mac mini means the monitor keeps running when the Mac mini is off.
  4. DH-13 closed by a GitHub environment. Every production secret is a secret of the environment production, never a repository secret, and that environment's deployment branches are main only. Every job that reads one names environment: production, and none of those jobs runs for a pull request (their if: requires a push or a manual run of refs/heads/main). A pull request or branch that edits a workflow to name the environment is refused its secrets by GitHub, not by our YAML. tests/infra/ci-workflow.test.ts fails if a job reads a production secret outside the environment, if an environment job can run on pull_request, if pull_request_target appears, or if a workflow lacks permissions: contents: read at the top and in every job. Secrets are given to the steps that use them only, not to the whole job.
  5. The deploy guard (#297, PR #329) stays. deploy-nas and smoke-nas read main's head with git ls-remote origin refs/heads/main, through the GITHUB_TOKEN (contents: read) that actions/checkout leaves for origin, and skip a commit main has moved past.
  6. The image registry, when slice 1 builds it, is GitHub's:ghcr.io/feaw-serv/getmy-books. Nothing pushes an image yet.
  7. NAS reads of the repository need a token. The repository is private. The NAS receives code over SSH from deploy-nas and pulls nothing from git, so only the optional daily drift check against main's manifest (getmy-books-drift-check URL) reads GitHub. It sends a fine-grained, read-only token (this repository, Contents: read) from a root-owned repo-read.env when one is installed. The token is an owner step.

What this supersedes ​

  • ADR 0019, the deploy flow host: the pipeline is GitHub Actions, and DOPPLER_TOKEN_PRD is an environment secret, not a runner variable.
  • ADR 0028, the container registry and the reason keyless Sigstore was ruled out (GitHub is an OIDC issuer Fulcio accepts, so it is now an option for slice 1, not a decision).
  • ADR 0039, the docs build default: it now defaults REPO_URL to https://github.com/FEAW-Serv/getmy-books and uses GitHub's link paths.
  • Deploy-hardening plan, P1 option 2 and DH-13 (#71 stage 2, a pull-based deploy agent and builder outside the old host's Actions): replaced by decision 4.
  • ADRs 0014, 0023, 0026, 0027 and 0030 describe the previous host as a matter of record; each carries a dated note pointing here and is otherwise unchanged.

Consequences ​

  • Production secrets can no longer be read from a branch: P1 closes once a branch run is shown not to get them.
  • GitHub's hosted runners are on the internet and are not the Mac mini, so deploy-docs, smoke-nas, alert-main-failed and Health send DOPPLER_TOKEN_PRD to a GitHub-hosted VM for the job's length. They are main-only and environment-gated. If a Doppler service token is ever restricted by source address, those jobs need GitHub's address ranges or the self-hosted runner.
  • The self-hosted runner runs container: jobs, which GitHub supports on Linux only. It runs inside Linux on the Mac mini (the Colima VM or a container in it), with Colima LAN routing and the NAS deploy key's from= list covering both of the Mac mini's interfaces.
  • Each environment job records a deployment on production, so Health records one every 15 minutes. Required reviewers on the environment would hold every Health run and every alert, so they are not recommended.
  • GitHub can re-run a job (gh run rerun), which eases P3; the deploy guard still stops an old run deploying over a newer main.
  • The sale documents now name a GitHub repository, which transfers between organisations with its history, issues and pull requests.