Zum Inhalt springen
Trainingslager IT-Trainingslager

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 automatisch self-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
ls

Erwartet:

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 lädt eine Datei aus einem Release – hier aus dem Repository actions/runner. -p wählt die Datei.
  • config.sh meldet den Runner bei GitHub an, run.sh startet ihn im Vordergrund, svc.sh richtet 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 lab

Erwartet (gekürzt):

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

√ Runner successfully added

# Runner settings

√ Settings Saved.
  • --labels lab hängt ein eigenes Label an. Jobs, die lab verlangen, landen hier.
  • Der Registrierungs-Token ist nach der Anmeldung verbraucht. Der Runner speichert stattdessen eigene Zugangsdaten in .credentials und .runner – diese Dateien sind so geheim wie ein Passwort.

Erst einmal im Vordergrund starten:

./run.sh

Erwartet:

√ 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 start

Erwartet (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 ubuntu lässt den Dienst als Benutzer ubuntu laufen – nie als root.
  • Jobs dürfen damit alles, was ubuntu darf. Auch Docker, denn ubuntu ist in der Gruppe docker – und die ist so mächtig wie root.

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.yml
  • runs-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.yml

Mit 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.txt

Erwartet: 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:

  1. Der Workflow vm.yml startet nur per workflow_dispatch – das darf nur, wer Schreibrechte hat. Der Workflow ci läuft weiter auf den Runnern von GitHub.
  2. GitHub fragt vor Läufen aus Forks nach einer Freigabe. Wie streng, steht hier:
gh api repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval

Erwartet:

{"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-approval

Erwartet:

{"approval_policy":"all_external_contributors"}

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

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

Erwartet:

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

Erwartet:

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

Erwartet:

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.yml

Nach einer Minute:

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

Erwartet:

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 --ephemeral nimmt 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.