30 Appendix: GitHub Actions Context & Expressions Referenz

Dieser Appendix beschreibt den GitHub Actions Context als zentrale Datenstruktur eines Workflow-Runs sowie die Expression-Syntax (${{ ... }}), mit der diese Daten im Workflow ausgewertet werden. Er dient als technische Referenz für Conditional Logic, Parametrisierung und dynamische Workflows.

30.1 Überblick: Context-Modell

GitHub Actions stellt während eines Workflow-Runs mehrere globale Context-Objekte bereit. Diese sind hierarchisch aufgebaut, read-only und während des gesamten Runs konsistent verfügbar.

Context	Beschreibung	Typischer Inhalt
`github`	Event- und Repository-Metadaten	Event-Payload, Ref, SHA
`env`	Environment-Variablen	Workflow-, Job-, Step-Ebene
`job`	Job-spezifische Informationen	Status, Container
`steps`	Step-Outputs und Outcomes	`steps.<id>.outputs.*`
`runner`	Runner-Informationen	OS, Arch, Pfade
`secrets`	Secrets	Repo-, Org-, Environment-Secrets
`matrix`	Aktuelle Matrix-Werte	`os`, `node`, …
`strategy`	Matrix-Definition	include / exclude
`needs`	Outputs abhängiger Jobs	Job-Orchestrierung
`inputs`	Manuelle / Reusable Inputs	workflow_dispatch, workflow_call

30.2 github Context – zentrale Felder

Feld	Bedeutung
`github.event_name`	Name des auslösenden Events
`github.event.action`	Activity Type (falls vorhanden)
`github.event`	Vollständiges Event-Payload (JSON)
`github.ref`	Vollständige Ref (`refs/heads/main`)
`github.ref_name`	Kurzform (`main`, `v1.0`)
`github.sha`	Commit SHA
`github.actor`	Auslösender User
`github.repository`	`owner/repo`
`github.repository_owner`	Owner
`github.workflow`	Name des Workflows
`github.job`	Aktuelle Job-ID
`github.run_id`	Eindeutige Run-ID
`github.run_number`	Laufende Nummer
`github.workspace`	Checkout-Verzeichnis

Beispiel:

- run: echo "Run ${{ github.run_number }} auf ${{ github.ref }}"

30.3 Event-spezifischer Zugriff (Beispiele)

Pull Request:

${{ github.event.pull_request.number }}
${{ github.event.pull_request.title }}
${{ github.event.pull_request.user.login }}

Issue:

${{ github.event.issue.number }}
${{ github.event.issue.labels.*.name }}

workflow_run:

${{ github.event.workflow_run.conclusion }}
${{ github.event.workflow_run.head_branch }}

repository_dispatch:

${{ github.event.client_payload.env }}

30.4 Expression-Syntax

Expressions werden mit ${{ ... }} ausgewertet. Sie können an nahezu allen Stellen im Workflow verwendet werden.

Verwendung:

if
env
with
runs-on
concurrency
matrix
outputs

Beispiel:

if: ${{ github.ref == 'refs/heads/main' }}

30.5 Operatoren

Typ	Operatoren
Vergleich	`==`, `!=`, `<`, `>`, `<=`, `>=`
Logik	`&&`, `\| \|`, `!`
Strings	`contains()`, `startsWith()`, `endsWith()`
Collections	`join()`, `fromJson()`

Beispiel:

if: contains(github.ref, 'release/')

30.6 Wichtige Funktionen

Funktion	Beschreibung
`success()`	Alle vorherigen Steps erfolgreich
`failure()`	Mindestens ein Step fehlgeschlagen
`cancelled()`	Workflow wurde abgebrochen
`always()`	Immer true
`hashFiles()`	Hash über Files
`toJson()`	Objekt → JSON
`fromJson()`	JSON → Objekt

Beispiel:

if: failure() || cancelled()

30.7 steps Context

Zugriff auf Outputs und Status vorheriger Steps.

Feld	Bedeutung
`steps.<id>.outputs.<name>`	Step-Output
`steps.<id>.outcome`	`success`, `failure`, `skipped`
`steps.<id>.conclusion`	Finaler Status

Beispiel:

if: steps.build.outcome == 'success'

30.8 needs Context (Job-Orchestrierung)

Feld	Bedeutung
`needs.<job>.outputs.*`	Outputs abhängiger Jobs
`needs.<job>.result`	`success`, `failure`, `skipped`

Beispiel:

if: needs.test.result == 'success'

30.9 matrix Context

Feld	Bedeutung
`matrix.<name>`	Aktueller Matrix-Wert

Beispiel:

runs-on: ${{ matrix.os }}

30.10 secrets Context

Secrets sind nur in Jobs und Steps verfügbar.

Beispiel:

env:
  API_TOKEN: ${{ secrets.API_TOKEN }}

Hinweis:

Secrets sind in Logs maskiert
Nicht in if-Expressions auswertbar

30.11 Typische Patterns

Branch-spezifische Logik:

if: github.ref_name == 'main'

PR vs Push unterscheiden:

if: github.event_name == 'pull_request'

Label-gesteuertes Verhalten:

if: contains(github.event.pull_request.labels.*.name, 'deploy')

30.12 Einschränkungen

Einschränkung	Beschreibung
Read-only	Context-Objekte nicht direkt änderbar
Kein Persistenzmodell	Gilt nur für aktuellen Run
Payload-Größe	Event-Payload begrenzt
secrets in if	Nicht erlaubt