Referenz · Vordefinierte Variablen & Kontexte

Vordefinierte Variablen & Kontexte

Was Forgejo dir automatisch in jeden Job gibt – als $FORGEJO_*-Umgebungsvariablen und als ${{ … }}-Kontexte.

Doppelte Namen: FORGEJO_ und GITHUB_ Jede injizierte Variable existiert zweimal: mit FORGEJO_- und mit GITHUB_-Präfix (Kompatibilität mit GitHub-Actions). Beide zeigen auf denselben Wert. Im Workshop bevorzugen wir FORGEJO_ – aber kopierte GitHub-Workflows mit $GITHUB_* funktionieren trotzdem.

Umgebungsvariablen (Shell-Zugriff via $NAME)

Variable	Bedeutung
`FORGEJO_REPOSITORY`	`owner/repo` des laufenden Repos.
`FORGEJO_ACTOR`	Benutzername, der den Lauf ausgelöst hat.
`FORGEJO_REF`	Voll-Ref, z. B. `refs/heads/main` oder `refs/pull/7/head`.
`FORGEJO_SHA`	Commit-SHA, der den Lauf ausgelöst hat.
`FORGEJO_EVENT_NAME`	Auslösendes Event, z. B. `push`, `pull_request`.
`FORGEJO_WORKSPACE`	Arbeitsverzeichnis im Job (wo `checkout` landet).
`FORGEJO_TOKEN` ★	Automatischer Token für API-Aufrufe. In Fork-PRs nur lesend. Kann keine weiteren Workflows auslösen.
`FORGEJO_SERVER_URL`	Basis-URL der Forgejo-Instanz.
`FORGEJO_API_URL`	Basis-URL der Forgejo-API.
`FORGEJO_OUTPUT`	Datei, in die ein Step Outputs schreibt (`echo "k=v" >> "$FORGEJO_OUTPUT"`).
`FORGEJO_ENV`	Datei, um Env-Variablen für folgende Steps zu setzen.

Variable

Bedeutung

FORGEJO_REPOSITORY

owner/repo des laufenden Repos.

FORGEJO_ACTOR

Benutzername, der den Lauf ausgelöst hat.

FORGEJO_REF

Voll-Ref, z. B. refs/heads/main oder refs/pull/7/head.

FORGEJO_SHA

Commit-SHA, der den Lauf ausgelöst hat.

FORGEJO_EVENT_NAME

Auslösendes Event, z. B. push, pull_request.

FORGEJO_WORKSPACE

Arbeitsverzeichnis im Job (wo checkout landet).

FORGEJO_TOKEN ★

Automatischer Token für API-Aufrufe. In Fork-PRs nur lesend. Kann keine weiteren Workflows auslösen.

FORGEJO_SERVER_URL

Basis-URL der Forgejo-Instanz.

FORGEJO_API_URL

Basis-URL der Forgejo-API.

FORGEJO_OUTPUT

Datei, in die ein Step Outputs schreibt (echo "k=v" >> "$FORGEJO_OUTPUT").

FORGEJO_ENV

Datei, um Env-Variablen für folgende Steps zu setzen.

Ausdrucks-Kontexte (${{ … }})

In YAML-Werten – nicht in der Shell. Forgejo wertet sie vor der Ausführung aus.

Kontext	Enthält
`forgejo` ★	Metadaten des Laufs: `forgejo.ref`, `forgejo.sha`, `forgejo.actor`, `forgejo.event_name`, `forgejo.repository` … Aliase: `github`, `forge`.
`secrets`	Repo-/Org-Secrets, z. B. `${{ secrets.REGISTRY_TOKEN }}`. In Fork-PRs leer.
`vars`	Nicht-geheime Repo-/Org-Variablen.
`env`	Im Workflow definierte Umgebungsvariablen.
`matrix`	Werte der aktuellen Matrix-Zelle, z. B. `${{ matrix.python }}`.
`steps`	Outputs vorheriger Steps (mit `id:`), z. B. `${{ steps.v.outputs.ver }}`.
`needs`	Outputs von Jobs aus `needs`, z. B. `${{ needs.build.outputs.ver }}`.
`inputs`	Eingaben einer reusable workflow / eines `workflow_dispatch`.
`runner`	Infos zum Runner (OS, Architektur).

Kontext

Enthält

forgejo ★

Metadaten des Laufs: forgejo.ref, forgejo.sha, forgejo.actor, forgejo.event_name, forgejo.repository … Aliase: github, forge.

secrets

Repo-/Org-Secrets, z. B. ${{ secrets.REGISTRY_TOKEN }}. In Fork-PRs leer.

vars

Nicht-geheime Repo-/Org-Variablen.

env

Im Workflow definierte Umgebungsvariablen.

matrix

Werte der aktuellen Matrix-Zelle, z. B. ${{ matrix.python }}.

steps

Outputs vorheriger Steps (mit id:), z. B. ${{ steps.v.outputs.ver }}.

needs

Outputs von Jobs aus needs, z. B. ${{ needs.build.outputs.ver }}.

inputs

Eingaben einer reusable workflow / eines workflow_dispatch.

runner

Infos zum Runner (OS, Architektur).

Nützliche Ausdrucks-Funktionen

Funktion	Zweck
`success()`	True, solange kein vorheriger Step/Job fehlschlug (Default für Steps).
`failure()`	True, sobald etwas fehlgeschlagen ist – für Aufräum-/Melde-Steps.
`always()`	Läuft immer, auch nach Fehler oder Abbruch.
`cancelled()`	True, wenn der Lauf abgebrochen wurde.
`fromJSON()` / `toJSON()`	JSON parsen / erzeugen (z. B. dynamische Matrix).
`hashFiles()`	Hash über Dateien – ideal als Cache-Key.

Funktion

Zweck

success()

True, solange kein vorheriger Step/Job fehlschlug (Default für Steps).

failure()

True, sobald etwas fehlgeschlagen ist – für Aufräum-/Melde-Steps.

always()

Läuft immer, auch nach Fehler oder Abbruch.

cancelled()

True, wenn der Lauf abgebrochen wurde.

fromJSON() / toJSON()

JSON parsen / erzeugen (z. B. dynamische Matrix).

hashFiles()

Hash über Dateien – ideal als Cache-Key.

Faustregel $FORGEJO_REF in der Shell (im run:), ${{ forgejo.ref }} im YAML-Wert (z. B. in if: oder name:). Beide liefern dieselbe Information.

Vordefinierte Variablen & Kontexte

Umgebungsvariablen (Shell-Zugriff via `$NAME`)

Ausdrucks-Kontexte (`${{ … }}`)

Nützliche Ausdrucks-Funktionen

Vordefinierte Variablen & Kontexte

Umgebungsvariablen (Shell-Zugriff via $NAME)

Ausdrucks-Kontexte (${{ … }})

Nützliche Ausdrucks-Funktionen

Umgebungsvariablen (Shell-Zugriff via `$NAME`)

Ausdrucks-Kontexte (`${{ … }}`)