An ephemeral runner is a self-hosted workflow runner that accepts one job, then stops requesting work and deregisters. It can run on a VM, container, Kubernetes, or another environment that runs the .NET-based runner application. The single-job lifecycle enables cleanup or replacement of the execution environment between jobs. section 5.3 section 6.3.1
Use ephemeral runners to reduce persistence and make workloads reproducible:
- Start each job on a fresh runner to prevent files or data from one job being reused by a later job. section 6.3
- Declare required tools in the job definition rather than relying on cached files or preinstalled software on a long-lived machine. section 6.3
- For untrusted pull-request work, combine a contained single-use runner with no network access and stringent automated and manual checks. section 6.2
- Treat runner shutdown separately from infrastructure cleanup: an ephemeral runner on a VM deregisters, but the VM can remain running. section 6.3.1
Configure and clean up a single-use VM runner
Add --ephemeral when configuring the runner. It waits for one job, executes it, deregisters, and stops. Use the ACTIONS_RUNNER_HOOK_JOB_COMPLETED hook to remove the VM and provision a replacement when needed. section 6.3.1
At scale, create runners on demand when jobs queue and remove them on completion, optionally keeping a standby pool for slower startup paths. Actions Runner Controller (ARC) uses ephemeral containers by default: each container executes one job and exits, while Kubernetes starts replacements through replica sets. section 7.2.1 section 6.5.1
