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 App installed for the target organisation, with a runner group available for the pool

Setup ​

1. Create the GitHub App secret ​

bash
kubectl create secret generic github-runner-app -n default \
  --from-file=github-app-private-key=<app-private-key.pem> \
  --from-literal=github-app-id=<app-id> \
  --from-literal=github-app-installation-id=<installation-id>

2. Create a VMClass and template ​

yaml
apiVersion: imp.dev/v1alpha1
kind: ImpVMClass
metadata:
  name: runner-class
  namespace: default
spec:
  vcpu: 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-app
    tokenSource: github_app
    scope:
      org: my-org
    runnerGroup: imp-runners
  scaling:
    mode: polling
    minIdle: 1
    maxConcurrent: 5
    scaleUpStep: 1
    cooldownSeconds: 30
    polling:
      enabled: true
      intervalSeconds: 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-app -n default

Runners deregister from GitHub automatically on VM deletion.