Skip to content

Home / Blog / Cost and billing

What is an ephemeral runner, and why does it matter for CI security?

An ephemeral runner takes one job and is removed. How it differs from a just-in-time runner, why a fresh registration is not a clean machine, and what it costs.

An ephemeral runner takes at most 1 job and is then removed. GitHub assigns it a single job and deregisters it afterwards, whether you registered it with the --ephemeral flag or created it as a just-in-time runner through the REST API, and whoever operates the machine throws the environment away. It matters for security because a job that compromises a persistent runner can leave it compromised for the jobs that follow. Our GitHub self-hosted runner guide counts the full cost.

In short
  • An ephemeral runner takes at most 1 job and is then removed; GitHub assigns it a single job and deregisters it.
  • Register one with the --ephemeral flag, or create a just-in-time runner through the REST API.
  • GitHub recommends ephemeral runners for autoscaling, and does not recommend persistent runners for it.
  • Ephemeral registration is not a clean machine: GitHub says reusing hardware for just-in-time runners can expose information.
  • On runners.io each job has its own single-use runner and its own virtual machine, which no other job uses.

This page is the concept only: what the word means, how the two kinds of ephemeral runner differ, and what ephemeral does and does not guarantee. It does not cover running a fleet of them, which GitHub documents and which is a job in its own right. Every GitHub statement was read from GitHub’s pages on the date this post was last checked.

What is the difference between a persistent and an ephemeral runner?

Compared onPersistent runnerEphemeral runner
How many jobs it runsJob after job, until you remove itAt most 1. GitHub assigns it one job and deregisters it afterwards
What can be left behindSensitive resources from earlier jobs. Untrusted code in a workflow can compromise it persistentlyOnly what the machine itself keeps. GitHub warns that re-using hardware to host just-in-time runners can risk exposing information from the environment, and advises using automation to give each one a clean environment
How it registersWith a time-limited registration tokenWith the --ephemeral flag, or as a just-in-time runner made through the REST API without a time-limited registration token
GitHub's advice for autoscalingNot recommendedRecommended
Warm state such as caches and installed dependencies (our reading, not GitHub's)Stays on the disk between jobsStarts empty when each job gets a clean environment, as it should. Anything you want warm has to come back from a prepared image or a cache service

What is the difference between an ephemeral runner and a just-in-time runner?

Both run 1 job, and the difference is how they register. An ephemeral runner registers as usual, with a registration token and the --ephemeral flag, and GitHub removes it after its job. A just-in-time runner is made through the REST API: you call the endpoint for the organization or the repository, which returns an encoded configuration to pass to the runner application when it starts, and the runner is limited to a single job and then removed. GitHub’s announcement says the point is to create single-use runners without time-limited registration tokens, limiting the exposure of long-lived credentials. The REST reference itself does not use the words single-use for the configuration, so the changelog is the page that says it.

Does ephemeral mean the machine is clean?

Not by itself. Ephemeral describes the registration: one job, then the runner is gone from GitHub. It says nothing about the machine under it. GitHub’s secure use guidance says that re-using the same hardware to host just-in-time runners can still risk exposing information from the environment, and tells you to use automation to give each runner a clean one. It adds that a system which only destroys a self-hosted runner after each job, without ephemeral registration, might not be as effective as intended, because there is no way to guarantee a self-hosted runner only runs one job. Ephemeral registration and a fresh machine are 2 controls, and you want both.

What does an ephemeral runner cost you?

Warm state. A persistent runner keeps its disk between jobs, so a restored dependency or a built layer is still there for the next one, and an ephemeral runner starts without it. That is our reading and not a GitHub statement. The way back to speed is a cache the runner reaches over the network, such as the Actions cache, and the post on keeping a build directory between runs covers when that is not enough.

Where does runners.io stand?

Both ideas are in place. Each job gets its own single-use runner, registered on your repository for that one job, and its own virtual machine, started fresh from our image and shared with no other job. When the job ends the machine is destroyed, or rebuilt from the image, and a rebuild erases its disk, memory and firmware state. What outlasts a job does so because you kept it, in the cache, the layer cache or a sticky disk. The security documentation says it in full and Every job in its own virtual machine explains what it rules out. Whether ephemeral runners make a public repository safe is a separate question, which we answer in Is it safe to use self-hosted runners on a public repository? Our self-hosted runner alternative page sets out the other way: the same runs-on line, and no machines of your own to patch or scale.

Sources

Frequently asked questions

What is an ephemeral GitHub Actions runner?

A self-hosted runner that takes at most 1 job and is then removed. GitHub assigns it a single job and deregisters it afterwards, whether you registered it with the --ephemeral flag or created it as a just-in-time runner through the REST API.

What is the difference between an ephemeral runner and a just-in-time runner?

Both run 1 job. An ephemeral runner registers with a registration token and the --ephemeral flag. A just-in-time runner is made through the REST API, which returns a configuration for the runner to start with, and avoids time-limited registration tokens.

Does an ephemeral runner mean the machine is clean?

No. Ephemeral describes the registration. GitHub warns that re-using hardware to host just-in-time runners can still risk exposing information, and advises using automation to give each one a clean environment. You want both controls.

Why does an ephemeral runner matter for CI security?

A persistent runner can be persistently compromised by untrusted code in a workflow. GitHub recommends ephemeral runners for autoscaling because they limit the exposure of resources from previous jobs, and one job per runner means jobs are not sent to a runner that is shutting down.

Move your CI onto our runners with one line

Change one line, watch your own build, then decide.

Connect GitHub

Card required. You pay only for the minutes your jobs run.

.github/workflows/ci.yml
jobs: test:removed: runs-on: ubuntu-latestadded: runs-on: runnersio-4vcpu-ubuntu-2604 steps: - uses: actions/checkout@v4 - run: make testadded: build:added: runs-on: runnersio-32vcpu-ubuntu-2604