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 hasself-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
lsExpected:
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 downloaddownloads a file from a release – here from theactions/runnerrepository.-pselects the file.config.shregisters the runner with GitHub,run.shstarts it in the foreground,svc.shsets 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 labExpected (shortened):
--------------------------------------------------------------------------------
| ____ _ _ _ _ _ _ _ _ |
...
# Runner Registration
√ Runner successfully added
# Runner settings
√ Settings Saved.
--labels labadds a label of your own. Jobs that requirelabend up here.- The registration token is used up after registration. Instead, the
runner stores its own credentials in
.credentialsand.runner– these files are as secret as a password.
First start it in the foreground:
./run.shExpected:
√ 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 startExpected (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 ubuntumakes the service run as the userubuntu– never asroot.- Jobs may therefore do everything
ubuntumay do. Including Docker, becauseubuntuis in thedockergroup – and that is as powerful asroot.
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.ymlruns-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.ymlWith 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.txtExpected: 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:
- The
vm.ymlworkflow starts only viaworkflow_dispatch– only someone with write access may do that. Theciworkflow keeps running on GitHub’s runners. - GitHub asks for approval before runs from forks. How strictly is shown here:
gh api repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approvalExpected:
{"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-approvalExpected:
{"approval_policy":"all_external_contributors"}
Save your progress? Sign up for free
Checkpoint
systemctl is-active actions.runner.<du>-notes-actions.gha-vm.serviceExpected:
active
gh api repos/{owner}/{repo}/actions/runners --jq '.runners[].status'Expected:
online
wc -l < ~/gha-lab/laeufe.txtExpected:
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.ymlAfter a minute:
gh run list --workflow gpu.yml --limit 1Expected:
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 --ephemeralaccepts 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.