Tag 5: Ein eigener Runner
Ziel: Den GitHub-Runner auf der Labor-VM installieren, als Dienst starten, Jobs gezielt auf ihn schicken und verstehen, warum ein eigener Runner anders ist als die Runner von GitHub – und gefährlich werden kann. · Dauer: ca. 60 min · Voraussetzung: Tag 4
Briefing
- Ein Self-hosted Runner ist ein Programm auf deinem Rechner. Es baut von sich aus eine HTTPS-Verbindung zu GitHub auf und fragt nach Jobs – kein offener Port nötig.
- Jobs wählen ihn über Labels:
runs-on: [self-hosted, lab]. Jeder Runner hat automatischself-hosted, sein Betriebssystem und seine Architektur. - Er ist nicht frisch: Dateien, installierte Pakete, Docker-Images und laufende Prozesse bleiben zwischen Jobs liegen.
- Wer einen Job auf ihm starten kann, führt Code auf deiner Maschine aus.
VM gha github.com
┌──────────────────────────────┐ HTTPS ┌──────────────────┐
│ actions-runner (Dienst) ────┼───────────► │ Job-Warteschlange│
│ _work/notes-actions/... │ (ausgehend)│ runs-on: lab │
└──────────────────────────────┘ └──────────────────┘
Drill 1: Runner herunterladen
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
lsErwartet:
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 downloadlädt eine Datei aus einem Release – hier aus dem Repositoryactions/runner.-pwählt die Datei.config.shmeldet den Runner bei GitHub an,run.shstartet ihn im Vordergrund,svc.shrichtet ihn als systemd-Dienst ein.- Auf einem ARM-Rechner heißt die Datei
actions-runner-linux-arm64-2.338.2.tar.gz.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Anmelden
Zum Anmelden braucht der Runner einen Registrierungs-Token. Er gilt eine Stunde und nur für dieses 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 labErwartet (gekürzt):
--------------------------------------------------------------------------------
| ____ _ _ _ _ _ _ _ _ |
...
# Runner Registration
√ Runner successfully added
# Runner settings
√ Settings Saved.
--labels labhängt ein eigenes Label an. Jobs, dielabverlangen, landen hier.- Der Registrierungs-Token ist nach der Anmeldung verbraucht. Der
Runner speichert stattdessen eigene Zugangsdaten in
.credentialsund.runner– diese Dateien sind so geheim wie ein Passwort.
Erst einmal im Vordergrund starten:
./run.shErwartet:
√ Connected to GitHub
Current runner version: '2.338.2'
2026-11-03 10:07:45Z: Listening for Jobs
Beende ihn mit Strg+C.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Als Dienst
Im Vordergrund stirbt der Runner mit deiner SSH-Sitzung. Als systemd-Dienst läuft er weiter und startet nach einem Neustart wieder:
sudo ./svc.sh install ubuntu
sudo ./svc.sh startErwartet (gekürzt):
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
...
Der Dienst heißt
actions.runner.<du>-notes-actions.gha-vm.service:
Besitzer, Repository und Name des Runners.
install ubuntulässt den Dienst als Benutzerubuntulaufen – nie alsroot.- Jobs dürfen damit alles, was
ubuntudarf. Auch Docker, dennubuntuist in der Gruppedocker– und die ist so mächtig wieroot.
Was GitHub über den Runner weiß:
cd ~/gha-lab/notes-actions
gh api repos/{owner}/{repo}/actions/runners \
--jq '.runners[] | .name, .status, [.labels[].name]'Erwartet:
gha-vm
online
["self-hosted","Linux","X64","lab"]
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein Job auf der 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]: Der Runner muss alle Labels der Liste haben.- Der zweite Step schreibt außerhalb des Arbeitsordners. Auf einem Runner von GitHub wäre die Datei nach dem Job weg – hier nicht.
Mit der ID aus gh run list --workflow vm.yml --limit 1,
sobald der Lauf fertig ist:
gh run view <ID> --log | grep -E 'Z (Host:|Arbeitsordner:|Lauf )'Erwartet (Zeitstempel und Pfad gekürzt, IDs weichen ab):
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
Ein zweiter Lauf:
gh workflow run vm.ymlMit der neuen ID, sobald der Lauf fertig ist:
gh run view <ID> --log | grep -E 'Z Lauf 'Erwartet:
wo Spuren hinterlassen 2026-11-03T10:08:49Z Lauf 41616747121
wo Spuren hinterlassen 2026-11-03T10:08:49Z Lauf 41616786324
Die Zeile aus dem ersten Lauf ist noch da. Genau das unterscheidet einen eigenen Runner von einem frischen: Was ein Job liegen lässt, sieht der nächste.
cat ~/gha-lab/laeufe.txtErwartet: dieselben zwei Zeilen – der Job lief wirklich auf deiner VM.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Wer darf Jobs starten?
Dein Repository ist öffentlich. Jeder kann es forken und einen
Pull-Request öffnen. Ein Workflow mit on: pull_request und
runs-on: self-hosted würde dann fremden Code auf deiner VM
ausführen. Zwei Schutzschichten:
- Der Workflow
vm.ymlstartet nur perworkflow_dispatch– das darf nur, wer Schreibrechte hat. Der Workflowciläuft weiter auf den Runnern von GitHub. - GitHub fragt vor Läufen aus Forks nach einer Freigabe. Wie streng, steht hier:
gh api repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approvalErwartet:
{"approval_policy":"first_time_contributors"}
Nur wer zum ersten Mal beiträgt, braucht eine Freigabe. Für ein Repository mit eigenem Runner: alle Externen.
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-approvalErwartet:
{"approval_policy":"all_external_contributors"}
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
systemctl is-active actions.runner.<du>-notes-actions.gha-vm.serviceErwartet:
active
gh api repos/{owner}/{repo}/actions/runners --jq '.runners[].status'Erwartet:
online
wc -l < ~/gha-lab/laeufe.txtErwartet:
2
Challenge
Schick einen Job an ein Label, das kein Runner hat, z. B.
gpu. Was zeigt gh run list? Brich den Lauf
ab.
Hinweis: Eine zweite Datei gpu.yml mit
workflow_dispatch. gh run cancel.
Lösung
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.ymlNach einer Minute:
gh run list --workflow gpu.yml --limit 1Erwartet:
STATUS TITLE WORKFLOW BRANCH EVENT ID ELAPSED AGE
* gpu gpu main workflow_di... 4161685... 1m6s about 1...
Der Job wartet – bis zu 24 Stunden lang, dann bricht GitHub ihn ab. Von Hand:
gh run cancel <ID>Die ID ist in der Tabelle gekürzt. Ganz zeigt sie
gh run list --workflow gpu.yml --limit 1 --json databaseId.
Erwartet:
✓ Request to cancel workflow 41616859892 submitted.
gh run list --workflow gpu.yml --limit 1 zeigt danach
X und in --json conclusion den Wert
cancelled.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Ephemere Runner:
config.sh --ephemeralnimmt genau einen Job an und meldet sich danach ab. Zusammen mit einer frischen VM oder einem frischen Container pro Job verschwindet das Problem der liegengebliebenen Spuren. Tag 14 macht das mit Actions Runner Controller auf Kubernetes. - Runner-Gruppen: In Organisationen bündeln Gruppen Runner und legen fest, welche Repositorys und Workflows sie nutzen dürfen.
- Nie öffentlich ohne Schutz: GitHub rät davon ab, eigene Runner für öffentliche Repositorys zu verwenden. Wenn doch, dann nur für Trigger, die Schreibrechte verlangen, und mit Freigabe für alle Externen.
- Updates: Der Runner aktualisiert sich selbst. Eine Version, die zu alt ist, nimmt GitHub nach einiger Zeit nicht mehr an.