Skip to content
Hands-on IT IT Drills

Day 5: A Runner of Your Own

Goal: Install the GitHub runner on the lab VM, start it as a service, send jobs to it deliberately and understand why a runner of your own is different from GitHub’s runners – and can become dangerous. · Duration: approx. 60 min · Prerequisite: Day 4

Briefing

  • A self-hosted runner is a program on your machine. It opens an HTTPS connection to GitHub on its own and asks for jobs – no open port needed.
  • Jobs select it via labels: runs-on: [self-hosted, lab]. Every runner automatically has self-hosted, its operating system and its architecture.
  • It is not fresh: files, installed packages, Docker images and running processes remain between jobs.
  • Whoever can start a job on it runs code on your machine.
 VM gha                                         github.com
 ┌──────────────────────────────┐   HTTPS     ┌──────────────────┐
 │ actions-runner (service) ────┼───────────► │ job queue        │
 │  _work/notes-actions/...     │  (outbound) │ runs-on: lab     │
 └──────────────────────────────┘             └──────────────────┘

Drill 1: Downloading the runner

mkdir -p ~/gha-lab/runner
cd ~/gha-lab/runner
gh release download v2.338.2 -R actions/runner \
  -p actions-runner-linux-x64-2.338.2.tar.gz
tar xzf actions-runner-linux-x64-2.338.2.tar.gz
ls

Expected:

actions-runner-linux-x64-2.338.2.tar.gz
bin
config.sh
env.sh
externals
run-helper.cmd.template
run-helper.sh.template
run.sh
safe_sleep.sh
svc.sh
  • gh release download downloads a file from a release – here from the actions/runner repository. -p selects the file.
  • config.sh registers the runner with GitHub, run.sh starts it in the foreground, svc.sh sets it up as a systemd service.
  • On an ARM machine the file is called actions-runner-linux-arm64-2.338.2.tar.gz.

Save your progress? Sign up for free

Drill 2: Registering

To register, the runner needs a registration token. It is valid for one hour and only for this repository:

TOKEN=$(gh api -X POST \
  repos/<du>/notes-actions/actions/runners/registration-token --jq .token)
./config.sh --unattended --url https://github.com/<du>/notes-actions \
  --token "$TOKEN" --name gha-vm --labels lab

Expected (shortened):

--------------------------------------------------------------------------------
|        ____ _ _   _   _       _          _        _   _                      |
...
# Runner Registration

√ Runner successfully added

# Runner settings

√ Settings Saved.
  • --labels lab adds a label of your own. Jobs that require lab end up here.
  • The registration token is used up after registration. Instead, the runner stores its own credentials in .credentials and .runner – these files are as secret as a password.

First start it in the foreground:

./run.sh

Expected:

√ Connected to GitHub

Current runner version: '2.338.2'
2026-11-03 10:07:45Z: Listening for Jobs

Stop it with Ctrl+C.

Save your progress? Sign up for free

Drill 3: As a service

In the foreground, the runner dies with your SSH session. As a systemd service it keeps running and starts again after a reboot:

sudo ./svc.sh install ubuntu
sudo ./svc.sh start

Expected (shortened):

Creating launch runner in /etc/systemd/system/actions.runner.<du>-notes-actions.gh...
Run as user: ubuntu
...
● actions.runner.<du>-notes-actions.gha-vm.service - GitHub Actions Runner (<du>-...
     Loaded: loaded (/etc/systemd/system/actions.runner.<du>-notes-actions.gha-vm....
     Active: active (running) since Tue 2026-11-03 10:08:10 UTC; 49ms ago
...

The service is called actions.runner.<du>-notes-actions.gha-vm.service: owner, repository and name of the runner.

  • install ubuntu makes the service run as the user ubuntu – never as root.
  • Jobs may therefore do everything ubuntu may do. Including Docker, because ubuntu is in the docker group – and that is as powerful as root.

What GitHub knows about the runner:

cd ~/gha-lab/notes-actions
gh api repos/{owner}/{repo}/actions/runners \
  --jq '.runners[] | .name, .status, [.labels[].name]'

Expected:

gha-vm
online
["self-hosted","Linux","X64","lab"]

Save your progress? Sign up for free

Drill 4: A job on the VM

cat > .github/workflows/vm.yml <<'EOF'
name: vm
on: workflow_dispatch

jobs:
  wo:
    runs-on: [self-hosted, lab]
    steps:
      - name: Wo bin ich?
        run: |
          echo "Host: $(hostname), Benutzer: $(whoami)"
          echo "Arbeitsordner: $PWD"
      - name: Spuren hinterlassen
        run: |
          echo "Lauf $GITHUB_RUN_ID" >> ~/gha-lab/laeufe.txt
          cat ~/gha-lab/laeufe.txt
EOF
git add .github
git commit -qm "vm: Job auf dem eigenen Runner"
git push -q
gh workflow run vm.yml
  • runs-on: [self-hosted, lab]: The runner must have all labels in the list.
  • The second step writes outside the working directory. On a GitHub runner, the file would be gone after the job – not here.

With the ID from gh run list --workflow vm.yml --limit 1, as soon as the run is finished:

gh run view <ID> --log | grep -E 'Z (Host:|Arbeitsordner:|Lauf )'

Expected (timestamps and path shortened, IDs differ):

wo  Wo bin ich? ... Host: gha, Benutzer: ubuntu
wo  Wo bin ich? ... Arbeitsordner: /home/ubuntu/gha-lab/runner/_work/notes-actions/no...
wo  Spuren hinterlassen ... Lauf 41616747121

A second run:

gh workflow run vm.yml

With the new ID, as soon as the run is finished:

gh run view <ID> --log | grep -E 'Z Lauf '

Expected:

wo  Spuren hinterlassen 2026-11-03T10:08:49Z Lauf 41616747121
wo  Spuren hinterlassen 2026-11-03T10:08:49Z Lauf 41616786324

The line from the first run is still there. That is exactly what distinguishes a runner of your own from a fresh one: whatever one job leaves behind, the next one sees.

cat ~/gha-lab/laeufe.txt

Expected: the same two lines – the job really ran on your VM.

Save your progress? Sign up for free

Drill 5: Who may start jobs?

Your repository is public. Anyone can fork it and open a pull request. A workflow with on: pull_request and runs-on: self-hosted would then run foreign code on your VM. Two layers of protection:

  1. The vm.yml workflow starts only via workflow_dispatch – only someone with write access may do that. The ci workflow keeps running on GitHub’s runners.
  2. GitHub asks for approval before runs from forks. How strictly is shown here:
gh api repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval

Expected:

{"approval_policy":"first_time_contributors"}

Only first-time contributors need approval. For a repository with its own runner: all external contributors.

gh api -X PUT repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval \
  -f approval_policy=all_external_contributors
gh api repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval

Expected:

{"approval_policy":"all_external_contributors"}

Save your progress? Sign up for free

Checkpoint

systemctl is-active actions.runner.<du>-notes-actions.gha-vm.service

Expected:

active
gh api repos/{owner}/{repo}/actions/runners --jq '.runners[].status'

Expected:

online
wc -l < ~/gha-lab/laeufe.txt

Expected:

2

Challenge

Send a job to a label that no runner has, e.g. gpu. What does gh run list show? Cancel the run.

Hint: A second file gpu.yml with workflow_dispatch. gh run cancel.

Solution

cat > .github/workflows/gpu.yml <<'EOF'
name: gpu
on: workflow_dispatch

jobs:
  rechnen:
    runs-on: [self-hosted, gpu]
    steps:
      - run: nvidia-smi
EOF
git add .github
git commit -qm "gpu: Job ohne passenden Runner"
git push -q
gh workflow run gpu.yml

After a minute:

gh run list --workflow gpu.yml --limit 1

Expected:

STATUS  TITLE  WORKFLOW  BRANCH  EVENT           ID          ELAPSED  AGE
*       gpu    gpu       main    workflow_di...  4161685...  1m6s     about 1...

The job waits – for up to 24 hours, then GitHub cancels it. Manually:

gh run cancel <ID>

The ID is truncated in the table. The full ID is shown by gh run list --workflow gpu.yml --limit 1 --json databaseId.

Expected:

✓ Request to cancel workflow 41616859892 submitted.

Afterwards, gh run list --workflow gpu.yml --limit 1 shows X and, in --json conclusion, the value cancelled.

Save your progress? Sign up for free

Enterprise Note

  • Ephemeral runners: config.sh --ephemeral accepts exactly one job and deregisters afterwards. Together with a fresh VM or a fresh container per job, the problem of leftover traces disappears. Day 14 does this with Actions Runner Controller on Kubernetes.
  • Runner groups: In organizations, groups bundle runners and define which repositories and workflows may use them.
  • Never public without protection: GitHub advises against using self-hosted runners for public repositories. If you do, then only for triggers that require write access, and with approval for all external contributors.
  • Updates: The runner updates itself. GitHub stops accepting a version that is too old after a while.