IMP

Appearance

Runner Pool E2E Runbook ​

End-to-end validation of ImpVMRunnerPool against a real GitHub Actions organization.

Prerequisites ​

  • Imp installed on a cluster with KVM-capable nodes
  • A GitHub organization or repository for runner registration
  • A GitHub PAT with repo scope (for repo-scoped runners) or manage_runners:org (for org-scoped)

Setup ​

1. Create the runner secret ​

bash
kubectl create secret generic github-runner-token -n default \
  --from-literal=token=<your-github-pat>

2. Create a VMClass and template ​

yaml
apiVersion: imp.dev/v1alpha1
kind: ImpVMClass
metadata:
  name: runner-class
  namespace: default
spec:
  cpu: 2
  memoryMiB: 2048
  diskGiB: 10
---
apiVersion: imp.dev/v1alpha1
kind: ImpVMTemplate
metadata:
  name: gh-runner
  namespace: default
spec:
  classRef:
    name: runner-class
  image: ghcr.io/syscode-labs/imp-runner:latest

3. Create the runner pool ​

yaml
apiVersion: imp.dev/v1alpha1
kind: ImpVMRunnerPool
metadata:
  name: ci-pool
  namespace: default
spec:
  templateName: gh-runner
  platform:
    type: github-actions
    credentialsSecret: github-runner-token
    scope:
      repo: my-org/my-repo   # or set org: my-org for org-scoped
  scaling:
    mode: polling
    minIdle: 1
    maxConcurrent: 5
    scaleUpStep: 1
    cooldownSeconds: 30

Verify ​

Kubernetes side ​

bash
kubectl get impvmrunnerpool ci-pool -n default -o yaml
kubectl get impvm -n default -l imp.dev/pool=ci-pool
kubectl logs -n imp-system deploy/imp-controller-manager -c manager | grep runnerpool

GitHub side ​

Check that runners appear as online in your repo/org:

GitHub → Settings → Actions → Runners

Trigger a job ​

Create a workflow that targets your runners:

yaml
# .github/workflows/test-imp-runner.yml
on: workflow_dispatch
jobs:
  run:
    runs-on: self-hosted
    steps:
      - run: echo "running on imp runner $(hostname)"

Dispatch it and confirm the job is picked up by one of the pool VMs.

Scaling validation ​

Set minIdle: 0 and queue multiple jobs. Confirm the pool scales up to maxConcurrent, respects scaleUpStep, and scales back down after cooldownSeconds.

Teardown ​

bash
kubectl delete impvmrunnerpool ci-pool -n default
kubectl delete secret github-runner-token -n default

Runners deregister from GitHub automatically on VM deletion.