Skip to content

Migrate self-hosted runner auth from fine-grained PAT to GitHub App #238

@JacobPEvans-personal

Description

@JacobPEvans-personal

Context

The orbstack-runner currently uses a fine-grained PAT (`GH_PAT_RUNNER_TOKEN` in Doppler `gh-workflow-tokens/prd`) mapped to `ACCESS_TOKEN` inside the container. Fine-grained PATs have a hard 1-year cap and no auto-rotation. When the PAT expires the LaunchAgent silently retries every 30s indefinitely and every PR with E2E coverage blocks. PR #237 added a preflight check that surfaces this failure mode but doesn't remove the root cause.

The recurring nature of this failure (it has blocked at least PR #234) makes the PAT model unsuitable long-term.

Proposed fix

`myoung34/github-runner` natively supports `APP_ID` + `APP_PRIVATE_KEY` env vars and mints registration tokens via installation tokens internally — auto-refreshing, never expires as long as the App stays installed.

Steps

  1. Create a GitHub App in the JacobPEvans org named `orbstack-runner-registration`:
    • Permissions: `Administration: Read & Write` (minimum for self-registration), `Metadata: Read`
    • Install on `orbstack-kubernetes` only (no org-wide install)
  2. Store `APP_ID` (integer) and `APP_PRIVATE_KEY` (PEM content) in Doppler `gh-workflow-tokens/prd`
  3. PR: swap `docker/actions-runner/docker-compose.yml`:
    • Remove `ACCESS_TOKEN: ${GH_PAT_RUNNER_TOKEN…}`
    • Add `APP_ID: ${GH_APP_ID}` and `APP_PRIVATE_KEY: ${GH_APP_PRIVATE_KEY}`
    • Update header comment block (lines 26–28) to reference the new env vars
  4. Update `make runner-preflight` to assert `GH_APP_ID` and `GH_APP_PRIVATE_KEY` are non-empty (replace the `GH_PAT_RUNNER_TOKEN` assertion)
  5. Verify one E2E job picks up cleanly on the new auth, then remove `GH_PAT_RUNNER_TOKEN` from Doppler

Refs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions