Forgejo Pipelines · Workshop Lektion 1 / Einführung

Was sind Forgejo Actions?

Dein erstes .forgejo/workflows/ci.yaml – eine echte App testet sich selbst.

Warum das zählt
Am Ende dieser Lektion verstehst du das Vokabular (Workflow, Job, Step, Runner) und wer deine Pipeline eigentlich ausführt. Du kannst eine erste lauffähige Pipeline lesen und schreiben. Das ist das Fundament, auf dem jede weitere Lektion – und dein Workshop – aufbaut.

Unser durchgehendes Beispiel

Statt „Hello World" begleitet uns durch den ganzen Kurs eine kleine, echte App: eine FastAPI-„Tasks"-API in Python – ein Service, der Aufgaben verwaltet. Das Repo enthält ungefähr das hier: 

tasks-api/
├── app/
│   └── main.py          # die FastAPI-App
├── tests/
│   └── test_main.py     # pytest-Tests
├── requirements.txt
└── .forgejo/
    └── workflows/
        └── ci.yaml      # ← darum geht es

Jedes Mal, wenn jemand Code pusht, soll Forgejo automatisch prüfen: Ist der Code sauber formatiert? Laufen die Tests durch? Diesen automatisierten Ablauf nennt Forgejo einen Workflow – umgangssprachlich eine Pipeline.

Der wichtigste Satz des ganzen Workshops

Bevor wir YAML schreiben, brauchst du ein mentales Modell – es erklärt später fast jedes „Warum läuft das nicht?":

Forgejo führt deine Jobs nicht selbst aus Der Forgejo-Server speichert deinen Workflow und verteilt die Arbeit. Ausgeführt wird sie von einem separaten Programm, dem Forgejo Runner, der die Jobs aktiv abholt („pollt") und sie mit der Engine act – meist in einem Container – abarbeitet.

git push

du committest
→

Forgejo

reiht Job ein
→

Runner

holt Job ab
→

act

führt Steps aus
Vom Push bis zur Ausführung: Forgejo verteilt, der Runner führt aus.
Bewusst kompatibel zu GitHub Actions Forgejo Actions nutzt dieselbe YAML-Struktur und dieselben ${{ … }}-Ausdrücke wie GitHub Actions. Vieles, das du dort findest, gilt analog. Die gezielten Unterschiede markieren wir im Kurs immer mit dem ★ Forgejo-Besonderheit-Kasten.

Die vier Begriffe

Ein Workflow besteht aus vier Bausteinen. Mehr brauchst du fürs Erste nicht:

Kein „stages" wie bei GitLab GitLab ordnet über stages:. Forgejo/GitHub kennt das nicht: Jobs laufen parallel, und die Reihenfolge stellst du mit needs: her (Lektion 2). Innerhalb eines Jobs laufen die Steps immer sequenziell.

Die erste ci.yaml

Die ganze Pipeline lebt in einer YAML-Datei unter .forgejo/workflows/. Hier ist sie – Zeile für Zeile danach erklärt:

.forgejo/workflows/ci.yaml
name: CI
on: [push]

jobs:
  lint:
    runs-on: docker
    container: python:3.12-slim
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff
      - run: ruff check app tests

  test:
    runs-on: docker
    container: python:3.12-slim
    needs: [lint]
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: pytest -q

Was hier passiert

Dein erster Win Du kannst diese Datei jetzt lesen und in Worten erklären, was beim nächsten Push passiert: Forgejo reiht die Jobs ein, ein Runner holt lint, führt es mit act im Container aus – und nur wenn das grün ist, danach test.

Parallelen: GitLab CI ↔ Forgejo Actions

Viele kommen aus der GitLab-Welt. Die guten Nachrichten: die Konzepte sind fast dieselben, nur anders benannt und etwas anders verdrahtet. Diese Übersetzungstabelle begleitet uns durch den ganzen Kurs:

GitLab CI

Eine Datei: .gitlab-ci.yml

Ordnung über stages:

Job hat ein script:

Wiederverwenden: include / extends

Runner-Auswahl über tags

Vordefiniert: CI_COMMIT_SHA …

GitLab-Server-Runner führt aus

Forgejo Actions

Mehrere: .forgejo/workflows/*.yaml

Ordnung über needs: (kein stages)

Step ist run: oder uses:

Wiederverwenden: uses / reusable workflows

Runner-Auswahl über runs-on + Label

Vordefiniert: FORGEJO_SHA …

Externer Runner + act führt aus

Die eine wirklich neue Idee Der grösste konzeptionelle Sprung von GitLab ist die Action – ein fertiger, per uses: eingebundener Baustein (wie actions/checkout). GitLab hat dafür kein direktes Gegenstück. Wie Forgejo solche Actions auflöst, ist eine eigene Besonderheit (Lektion 6).

Besonderheiten & Stolperfallen

Ohne passenden Runner läuft nichts Bleibt ein Job „waiting" hängen, passt fast immer das runs-on:-Label zu keinem registrierten Runner. Das Label ist freie Wahl bei der Runner-Registrierung – docker ist nur Konvention, kein Zauberwort.
Verzeichnis & Endung Workflows müssen unter .forgejo/workflows/ liegen, Endung .yaml oder .yml. Forgejo liest aus Kompatibilität auch .github/workflows/ – im Workshop nutzen wir aber konsequent .forgejo/.
Einrückung mit Leerzeichen YAML ist tab-feindlich. Immer Leerzeichen (2 pro Ebene), nie Tabs – sonst bricht der Workflow mit einem schwer auffindbaren Syntaxfehler.
Actions vorerst hinnehmen uses: actions/checkout@v4 bindet eine fertige Action ein. Wie Forgejo diese Adresse auflöst (ohne Marketplace!) ist eine echte Besonderheit – die schauen wir uns in Lektion 6 genau an. Fürs Erste: es klont dein Repo.

Kurz prüfen (aus dem Kopf)

Nicht spicken – Abrufen aus dem Gedächtnis ist genau die Übung, die hängen bleibt.

Wer führt die Steps einer Forgejo-Pipeline tatsächlich aus?

Wie stellst du in Forgejo eine Reihenfolge zwischen Jobs her?

Wozu dient das Label in runs-on: docker genau?

Primärquelle zum Lesen Forgejo Docs – Actions: Basic concepts. Die maßgebliche Begriffs-Definition. Lies sie und prüfe unser mentales Modell gegen – du wirst Workflow, Job, Step, Runner und Label jetzt wiedererkennen.
Ich bin dein Teacher. Wenn etwas unklar ist – warum der Runner pollt, was act genau ist, wie das FastAPI-Beispiel aussieht, oder wie sich das zu GitLab verhält – frag einfach im Chat. Genau dafür bin ich da.
Glossar & Keyword-Referenz Kursübersicht
Als Nächstes: Lektion 2 – Jobs, Reihenfolge & needs (parallele Jobs, Ordnung ohne stages)