Skip to content

GitHub Actions — private repo and self-hosted runner (VPS) ​

Lovely Home uses many workflows (CI, platform provision/deprovision, hub CD, Terraform). On a private repository, GitHub-hosted minutes are capped by plan; self-hosted runners do not consume those minutes (you pay for the VPS only).

GitHub-hosted minutes (private repo) ​

Plan (typical)Included Actions minutes / month
Free2,000
Pro3,000
Team / EnterpriseHigher

Overage is billed or jobs queue/fail depending on settings. Self-hosted runners are unlimited from GitHub’s billing perspective.

Check usage: GitHub → Settings → Billing → Plans and usage → Actions.

WorkloadRunnerWhy
CI (ci.yml — lint, test, build smoke)GitHub ubuntu-latest or self-hostedShort; OK on hosted if volume is low
Hub smoke (Playwright on demo)Self-hostedBrowser + deps; saves hosted minutes
CD — Hub Pages (cd-hub-pages.yml)Public-repo dispatch → ubuntu-latestThin private dispatch; build + parallel wrangler deploys on public CD (free minutes)
Platform provision / deprovision / registrySelf-hostedTerraform + wrangler + secrets
Hub lifecycle (hub-lifecycle.yml)Self-hostedStripe e2e, long
Terraform validateEitherFast
Prune workflow runs (prune-workflow-runs.yml)Self-hostedAPI calls only, every 6 hours

Start with CD + platform provision on the VPS; leave CI test on GitHub until you hit limits, then move smoke or all of CI.

VPS sizing ​

One small Linux VM is enough to start:

  • 2 vCPU, 4 GB RAM, 40 GB disk (e.g. Hetzner CX22, DO Basic)
  • Ubuntu 24.04 LTS
  • Static IP optional; outbound HTTPS required (GitHub, Cloudflare, npm, Stripe for lifecycle)

Install once on the box:

  • Node 24 (match .nvmrc / scripts/check-node-version.mjs)
  • git, curl, unzip
  • Terraform ≥ 1.6 (platform workflows)
  • Playwright (hub-smoke / lifecycle): the gha user cannot sudo in CI. Once as root from a repo checkout:
    bash
    sudo bash scripts/vps-install-playwright-deps.sh
    CI runs npx playwright install chromium only (no --with-deps).
  • Optional: cache ~/.npm between jobs

Do not commit Cloudflare or Stripe secrets onto the VPS disk beyond what the runner receives from GitHub Secrets per job.

Register the runner ​

  1. GitHub → repo → Settings → Actions → Runners → New self-hosted runner.
  2. Choose Linux x64, follow the download/config.sh steps.
  3. Use labels: self-hosted, Linux, X64. Optionally add lovely-home as an extra label in Settings → Actions → Runners (the runner name is not used for job matching).

Run the agent as a dedicated user (e.g. gha) under systemd so it survives reboots — GitHub docs.

Repo-level runner is enough for a single maintainer; use an org runner only if you add more repos.

Point workflows at the VPS ​

When the runner is online, change runs-on for the jobs you want off hosted minutes:

yaml
runs-on: [self-hosted, Linux, X64]

Example — CD deploy matrix only (keep resolve / build on hosted if you prefer):

yaml
deploy:
  runs-on: [self-hosted, Linux, X64]

Example — platform-site-provision jobs: set both jobs to the same runs-on.

Use a repository variable if you want to toggle without editing every file (optional pattern):

yaml
runs-on: ${{ vars.SELF_HOSTED_RUNNER == 'true' && fromJSON('["self-hosted", "Linux", "X64"]') || 'ubuntu-latest' }}

Set Settings → Secrets and variables → Actions → Variables: SELF_HOSTED_RUNNER = true when the VPS runner is ready.

Private repo notes ​

Before Settings → General → Change visibility → Private:

  1. Actions minutes — expect all hosted jobs to count against the private quota until you migrate them.
  2. Cloudflare Pages / Workers — GitHub App integration works with private repos; reconnect if prompted after visibility change.
  3. Secrets — unchanged; ensure CLOUDFLARE_API_TOKEN, PLATFORM_GITHUB_TOKEN, Stripe secrets, etc. remain on the repo.
  4. Forks / collaborators — private limits who can clone; fine for a commercial product repo.

Making private (CLI):

bash
gh repo edit marklovely/home-dashboard --visibility private

Review billing in the GitHub UI before confirming.

Security ​

  • Self-hosted runners execute 任意 workflow code from PRs if you run PR workflows on them. For a private repo with trusted collaborators only, risk is lower than public fork PRs.
  • Prefer: run PR CI on ubuntu-latest and workflow_dispatch / main-only heavy jobs on self-hosted; or restrict self-hosted to main using if: github.ref == 'refs/heads/main' on deploy jobs.
  • Keep the runner OS patched; one runner per machine; no unrelated production services on the same VM.

Rollout checklist ​

  • [ ] VPS provisioned, Node 24 + Terraform installed
  • [ ] Runner online with labels self-hosted, Linux, X64 (shows Idle in GitHub)
  • [ ] Test: manual CD — Hub Pages with sites: demo using self-hosted deploy job
  • [ ] Migrate platform-site-provision / deprovision jobs
  • [ ] Set SELF_HOSTED_RUNNER=true (if using variable pattern) or merge workflow runs-on edits
  • [ ] Watch Billing → Actions for one week; move hub-smoke if hosted minutes spike
  • [ ] Set repository to private when comfortable
  • [ ] Set GitHub Actions spending limit / notifications so you get email before hard stop

Social draft generation (VPS cron) ​

Automated Lovely Home social drafts (D1 only, no publishing) use VPS cron to call workflow_dispatch on social-generate-draft.yml. GitHub’s built-in schedule is intentionally not used — it often skips slots on private repos with self-hosted runners.

One-time on the runner VPS. The runner runs as gha; your manual clone is often under ubuntu — that is fine. Do not git pull as gha in /home/ubuntu/... (permission denied).

If the repo is at /home/ubuntu/home-dashboard (typical):

bash
cd ~/home-dashboard && git pull   # as ubuntu
sudo REPO_DIR=/home/ubuntu/home-dashboard GHA_USER=ubuntu bash scripts/vps-install-social-generate-cron.sh

Or clone once for gha (add a repo deploy key for gha’s ~/.ssh/id_ed25519.pub, then):

bash
sudo -u gha git clone git@github.com:marklovely/home-dashboard.git /home/gha/home-dashboard
sudo bash scripts/vps-install-social-generate-cron.sh

Then edit /etc/lovely-home/social-generate-scheduler.env and set SOCIAL_SCHEDULER_GITHUB_TOKEN to a PAT with actions:write on this repo (a dedicated fine-grained token is best). Cron runs every 2 hours UTC (0 */2 * * *), uses flock to avoid overlapping cron invocations, and the dispatch script skips if a run is already queued or in progress.

Cron format: the installer adds # lovely-home-social-generate-cron as a separate comment line above the job (not mid-line — see social-generation-status.md).

Logs: /var/log/lovely-home/social-generate-cron.log

Manual test:

bash
sudo -u gha bash -lc 'set -a && source /etc/lovely-home/social-generate-scheduler.env && set +a && cd ~/home-dashboard && node scripts/dispatch-social-generate-draft.mjs'

Run history (30 days) ​

Prune workflow runs (prune-workflow-runs.yml, #1549) runs every 6 hours. It deletes completed runs older than 30 days in home-dashboard and lovely-hub-provision, and every main run of a workflow whose file has been removed (runs on other branches age out normally, so an open PR keeps its checks). Deleted runs lose their logs and artifacts for good.

Each delete takes about a second, so each repo gets at most 8 minutes a run, and it stops sooner if the token's hourly allowance gets low (300 calls left here, 2,000 on PUBLIC_CI_DISPATCH_TOKEN). The next run carries on, so a backlog clears over a day or two. To see what it would delete, run it by hand: dry run is ticked by default. Deleting a workflow file is enough to clear its history; nothing else needs doing.