Set Up an Ephemeral GitHub Actions Self-Hosted Runner on a Linux VPS

Most teams start with a self-hosted runner that stays online all day. It is easy, but every job leaves files, caches, and tokens behind. The next job can read them. In this guide, you will learn to build an ephemeral GitHub Actions self-hosted runner on a Linux VPS. Each runner takes one job, then it is deleted, and a clean one takes its place.

If you do not use GitHub and want a full self-hosted Git server with CI instead, check our Gitea self-hosted CI/CD with Docker Compose guide.

GitHub says autoscaling should use ephemeral runners, not persistent ones. An ephemeral runner gets only one job, and GitHub removes it after that job. This limits what a bad job can leave behind and stops a hacked runner from getting new jobs. 

Also, GitHub docs say you should clean the machine after the runner is removed.

Only the one-job mode gives you a real guarantee. If you just delete a normal runner after each job, GitHub cannot promise that the runner only ran one job. A JIT runner is different. It does at most one job and is removed automatically. We use JIT runners in this guide.

You will learn to build a small system on one Ubuntu 24.04 VPS or Ubuntu 26.04. It has four parts:

• A Docker image that holds the official GitHub runner, running as a normal user.
• A short script that asks GitHub for a one-job runner (a "just-in-time" or JIT runner) and starts it in a new container.
• A systemd service that runs this script all the time, so a new runner starts after each job.
• Log forwarding and cleanup, so you keep the logs, and no old data stays on the server.

This is one ephemeral GitHub Actions self-hosted runner for each job, with a new container every time.

Before you set up an ephemeral GitHub Actions self-hosted runner, check this list. You need:

• A Linux VPS with Ubuntu 24.04 or 26.04 LTS, 2 vCPU and 4 GB RAM or more, and root or sudo access. A PerLod Linux VPS works well, because you can pick the CPU and RAM that match your build size.
• A GitHub repository where you are an admin.
• Outbound HTTPS (port 443) to GitHub. The runner does not need any open inbound port.
• An x64 server. For ARM64, change x64 to arm64 in the build script below.

Note: Use this setup only for private repositories you trust. Self-hosted runners should never be used with public repositories, because anyone can open a pull request and run code on your runner.

The first step is to log in, update the system, and install the required tools:

Allow SSH, then turn on the firewall with the commands below:

We do not publish any container port, so Docker will not open anything to the internet.

You must remove old or unofficial Docker packages if you have it on your server:

Then, use the commands below to add Docker's official repository:

Once you are done, install Docker and test it with the commands below:

We run the loop script as root, so you do not need to add any user to the docker group. Do not install Docker with snap, because the runner can fail with it.

The script needs a token to ask GitHub for JIT runners. Create a fine-grained personal access token by following:

1. Open GitHub, then go to Settings, Developer settings, Personal access tokens, Fine-grained tokens.
2. Click Generate new token.
3. Under Repository access, choose Only select repositories and pick your repo.
4. Under Repository permissions, set Administration to Read and write.
5. Set a short expiry, such as 90 days, and copy the token.

This token only lives on the VPS. It never goes into the job container.

First, you must create the folders to build the runner image:

Then, create the entrypoint file. It starts the runner with the JIT config and removes the value from the environment:

Next, you must create the Dockerfile. Use the command below to create it:

Now you must create the build script with the commands below. It finds the latest runner release and checks the file hash before it builds:

Check that the image exists with the command below:

At this point, you must create the settings file and lock it down, because it holds your token. For this, use the commands below:

In nano, set GH_OWNER, GH_REPO, and GH_TOKEN to your real values. Save with Ctrl+O, press Enter, and exit with Ctrl+X. Leave LOG_HOST empty for now.

This script is the core of the ephemeral GitHub Actions self-hosted runner setup. For each round, it asks GitHub for a JIT runner, starts a fresh container, waits for the job to end, deletes the runner entry, and starts again.

To create the file, use the command below and set its correct permissions:

Note: Jobs in this setup cannot run docker build or use service containers, because the runner container has no Docker access on purpose. If you need Docker inside jobs, you can use a separate VPS for those jobs.

Now you can create the service file with the command below. The @ lets you start more than one runner slot later:

Start slot 1, make it start on boot, and watch the loop:

In GitHub, open your repo, then Settings, Actions, Runners. You should see one runner with the status Idle. To run two jobs at the same time, start another slot with sudo systemctl enable --now gh-runner@2.

Labels tell GitHub which jobs can use your ephemeral GitHub Actions self-hosted runner. The runner has the labels self-hosted, Linux, X64, and ephemeral. A workflow picks it with runs-on. If no runner matches, the job waits in the queue and fails after 24 hours.

You can create a test workflow in your repo. Run this from your local copy of the repo:

Paste this content, then commit and push it to the default branch:

Note: Use a custom label like ephemeral for these runners only. This keeps normal jobs from landing on them by mistake.

A short-lived runner limits the damage if something goes wrong, but it does not protect your secrets by itself. A leaked token can still be used after the runner is gone. In this step, you can lock down the GitHub token on your VPS and learn simple rules for the secrets your jobs use.

• Keep the GitHub token only in /etc/gh-runner/runner.env with chmod 600. Never put it in the image or in a workflow.
• Store job secrets in GitHub Secrets, not in the workflow file, and give each secret the lowest access it needs.
• Never pass secrets as command-line arguments. Another process can read them with ps.
• Set the default GITHUB_TOKEN to read-only in your repo settings, and raise it only for jobs that need more.
• Use OIDC for cloud logins when you can, so you do not store long-term keys.

For a full view of pipeline security, you can read our DevSecOps CI/CD integration guide.

Because the container is deleted after each job, its logs are lost with it. Logs from an ephemeral GitHub Actions self-hosted runner must be sent to an outside place. The script already does this in two ways.

By default, logs go to the host journal with the tag gh-runner. You can read them with:

To send logs to a remote server, set LOG_HOST to the address of a server that accepts TCP syslog on port 514 (rsyslog, Graylog, or similar):

Change the line to the real address, for example:

Once you are done, save and close the file. Restart the service:

Note: Make sure the remote server is up. If the Docker syslog driver cannot reach it, the container will not start.

The --rm flag already removes each container. You still need to update the runner image. GitHub stops sending jobs to a runner that is too old, and the runner updates itself at job start if it can. A fresh image avoids that delay.

You can rebuild the image every week with a cron job:

The next container uses the new image. Old image layers are removed by docker image prune -f inside the build script. Keep the VPS itself up to date with sudo apt update && sudo apt upgrade -y.

Now it is time to check that everything works. You can run the test workflow twice and look at the results. If the second run shows no old file, then each job gets a clean runner. Also, you can check the container name and the runner list on GitHub.

• In GitHub, open Actions, pick ephemeral-test, and click Run workflow.
• Watch the log. The first run should print Clean runner: no old file found.
• Run the workflow a second time. It should print the same clean message again. This proves the old file is gone.
• On the VPS, check that the container name changed:

• Check the runner list through the API. Replace the owner and repo, and use your token:

You should see only the current idle runner, and each new job gets a new name. Your ephemeral GitHub Actions self-hosted runner is now working.

Sometimes the runner does not start, or a job stays in the queue. Most problems come from a wrong label, a bad token, or a log server that can't be reached. Use the checks below to find the cause quickly:

• Job stays queued: the labels in runs-on do not match. Check RUNNER_LABELS and the workflow.
• JIT request fails with 403 or 404: the token lacks Administration: Read and write on the repo, or it expired.
• Container fails at start: run sudo journalctl -u gh-runner@1 -n 50 and read the error. If LOG_HOST is set, check that the log server is reachable.
• Network check: run a runner test from the image with ./config.sh --check, using your repo URL and a token, to see if GitHub domains are reachable.

At this point, you have a clean ephemeral GitHub Actions self-hosted runner on your own VPS. Each job runs in a new container with limited power, the runner is deleted from GitHub when the job ends, and a new one starts at once. Logs are kept outside the container, and the image stays fresh with a weekly rebuild.

Ready to try it? Use PerLod Linux VPS instances as isolated CI workers, with custom CPU and RAM and private-service access.