Codeberg und Forgejo Actions: Ein vollständiger Leitfaden für selbstgehostetes CI/CD

Stripe Testing Best Practices: From Test Cards to Production Confidence

Comprehensive guide to testing Stripe payment integrations — test cards, webhook simulation, checkout flows, edge cases, and CI/CD strategies for bulletproof payment systems.

Inhaltsverzeichnis

• Einleitung
• Erste Schritte mit der tea CLI
• Verwaltung von Secrets
• Forgejo Actions: Nicht ganz GitHub Actions
• Action URL Resolution
• Praktisches CI/CD-Beispiel
• Häufige Fallstricke und Lösungen
• Fazit

Einleitung

Codeberg ist eine Git-Hosting-Plattform für freie Software, die auf Forgejo basiert. In Europa gehostet, der DSGVO unterliegend und von einer Non-Profit-Organisation verwaltet, beantwortet sie eine einfache Frage: Was wäre, wenn Ihr Code-Hosting nicht den Preislaunen eines einzelnen Konzerns ausgeliefert wäre?

Wir sind nicht hier, um Ihnen Codeberg schmackhaft zu machen. Die Runner-Images sind minimal. Einige GitHub Actions haben keine Forgejo-Äquivalente. Aber für Teams, die ein selbstgehostetes CI/CD ohne Vendor-Lock-in wünschen, lohnt es sich, die Kompromisse zu verstehen.

Forgejo Actions sehen fast aus wie GitHub Actions. Das „fast“ verbirgt einige Tücken. Dieser Guide deckt den gesamten Workflow ab, vom CLI-Setup bis hin zu Production-Pipelines.

Erste Schritte mit der tea CLI

tea ist die offizielle CLI für Gitea und Forgejo. Sie übernimmt das Repo-Management, Issue-Tracking, Secrets und mehr direkt aus dem Terminal.

Installation

Authentifizierung

tea login add --name codeberg --url https://codeberg.org --token <TOKEN>

tea login default codeberg     # set as default
tea whoami                     # verify it works
```text

### Häufige Operationen

```bash
tea repos list                               # list your repos
tea repo create --name my-project --private  # create a new repo
tea issues list                              # check issues
tea pr create --title "Fix auth"             # open a pull request
tea open                                     # open repo in browser
```text

Verwenden Sie `--repo owner/repo` und `--login codeberg`, wenn Sie ein spezifisches Repository oder eine bestimmte Instanz ansprechen müssen.

---

## Verwaltung von Secrets

Secrets sind das Rückgrat jeder CI/CD-Pipeline. Sie werden für Deploy-Keys, API-Token und SSH-Zugangsdaten benötigt.

### Via CLI

```bash
tea actions secrets list                            # view existing secrets
tea actions secrets create DEPLOY_KEY               # create (prompts for value)
tea actions secrets delete DEPLOY_KEY               # remove a secret
```text

### Via Web UI

Navigieren Sie in Ihrem Browser zu `/{owner}/{repo}/settings/actions/secrets`.

### Via API

Für alles, was die CLI nicht abdeckt:

```bash
tea api /repos/{owner}/{repo}/actions/secrets \
  --method PUT \
  --body '{"name":"SSH_PRIVATE_KEY","data":"<base64-encoded-value>"}'
```text

### Einrichten eines SSH Deploy Keys

Hier ist ein praktisches Beispiel. Generieren Sie ein Schlüsselpaar, fügen Sie den öffentlichen Schlüssel der `authorized_keys` Ihres Servers hinzu und speichern Sie dann den privaten Schlüssel als Secret:

```bash
# Generate a deploy key
ssh-keygen -t ed25519 -f deploy_key -N ""

# Store the private key as a Codeberg secret
tea actions secrets create SSH_PRIVATE_KEY
# Paste the contents of deploy_key when prompted

# Add the public key to your target server
ssh-copy-id -i deploy_key.pub user@your-server.com
```text

Referenzieren Sie Secrets in Workflows mit `${{ secrets.SSH_PRIVATE_KEY }}`. Forgejo injiziert zudem automatisch nützliche Variablen: `FORGEJO_TOKEN`, `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `FORGEJO_REF` und `FORGEJO_SHA`.

---

## Forgejo Actions: Nicht ganz GitHub Actions

Forgejo Actions folgen einer Philosophie von „Vertrautheit vor Kompatibilität“. Das YAML sieht aus wie bei GitHub Actions, aber das Verhalten stimmt nicht immer überein. Diesen Abschnitt sollten Sie als Lesezeichen speichern.

### Wesentliche Unterschiede

| Aspekt | GitHub Actions | Forgejo Actions |
| -------- | --------------- | ----------------- |
| `permissions` auf Job-Ebene | Unterstützt | **Ignoriert** (auf Step-Ebene verwenden) |
| `timeout-minutes` auf Job-Ebene | Unterstützt | **Ignoriert** (auf Step-Ebene verwenden) |
| `continue-on-error` auf Job-Ebene | Unterstützt | **Ignoriert** (auf Step-Ebene verwenden) |
| Standard-Runner-Image | ubuntu-latest (vollständige Suite) | Debian bookworm + Node.js (minimal) |
| Kontextvariable | nur `github.*` | `forgejo.*`, `forge.*`, `github.*` (alle als Alias) |
| Action-Registry | GitHub Marketplace | `https://data.forgejo.org/` |
| LXC-Container | Nicht verfügbar | Unterstützt |

Die Unterscheidung zwischen Job-Ebene und Step-Ebene ist das größte Problem bei der Migration. Setzen Sie `timeout-minutes: 10` auf der Job-Ebene, bewirkt dies stillschweigend gar nichts. Verschieben Sie es in jeden einzelnen Step. Das Gleiche gilt für `permissions` und `continue-on-error`.

Das Runner-Image ist die zweite Überraschung. Das `ubuntu-latest` von GitHub wird mit Docker, SSH und Build-Tools ausgeliefert. Der Standard-Runner von Forgejo ist ein schlankes Debian-Image mit Node.js. Benötigen Sie SSH? Installieren Sie es. Benötigen Sie Docker? Installieren Sie es. Kleinere Images, aber ausführlichere Workflows.

---

## Action-URL-Auflösung

Auf GitHub funktioniert `actions/checkout@v4` einfach so. Auf Forgejo hängt die Auflösung von Kurzformen von der Instanz-Konfiguration ab. Verwenden Sie immer vollqualifizierte URLs, um Überraschungen zu vermeiden.

### Gängige Action-Mappings

| GitHub-Kurzform | Forgejo-URL |
| ----------------- | ------------- |
| `actions/checkout@v4` | `https://data.forgejo.org/actions/checkout@v4` |
| `actions/setup-node@v4` | `https://data.forgejo.org/actions/setup-node@v4` |
| `actions/setup-go@v5` | `https://data.forgejo.org/actions/setup-go@v5` |
| `actions/upload-artifact@v4` | `https://data.forgejo.org/actions/upload-artifact@v4` |
| `actions/download-artifact@v4` | `https://data.forgejo.org/actions/download-artifact@v4` |
| `actions/cache@v4` | `https://data.forgejo.org/actions/cache@v4` |

Für Actions, die nur auf GitHub existieren, referenzieren Sie diese direkt:

```yaml
- uses: https://github.com/appleboy/ssh-action@v1
```text

Hinweis: Der Runner muss `github.com` erreichen können, damit dies funktioniert. In Air-Gapped-Setups sollten Sie diese Actions spiegeln oder als Vendor-Kopie einbinden.

---

## Praktisches CI/CD-Beispiel

Hier ist ein vollständiger Deployment-Workflow, der eine Node.js-App baut und diese via SSH bereitstellt:

```yaml
# .forgejo/workflows/deploy.yml
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: docker  # Forgejo uses 'docker' label, not 'ubuntu-latest'
    steps:
      # Step-level timeout matters — job-level is ignored
      - name: Checkout
        timeout-minutes: 5
        uses: https://data.forgejo.org/actions/checkout@v4

      - name: Setup Node.js
        timeout-minutes: 5
        uses: https://data.forgejo.org/actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install dependencies
        timeout-minutes: 10
        run: npm ci

      - name: Build
        timeout-minutes: 5
        run: npm run build

      # The runner is minimal — install SSH if the action needs it
      - name: Install SSH client
        timeout-minutes: 2
        run: apt-get update && apt-get install -y openssh-client

      # appleboy/ssh-action has no Forgejo mirror, use GitHub directly
      - name: Deploy via SSH
        timeout-minutes: 5
        uses: https://github.com/appleboy/ssh-action@v1
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/app
            git pull origin main
            npm ci --production
            pm2 restart app
```text

Beachten Sie die Forgejo-spezifischen Entscheidungen: das `docker` Runner-Label, vollqualifizierte Action-URLs und die explizite Installation des SSH-Clients. Lassen Sie einen dieser Punkte weg, und Ihre Pipeline bricht ab.

---

## Häufige Fallstricke und Lösungen

| Problem | Ursache | Lösung |
| --------- | ------- | ----- |
| `timeout-minutes` wird ignoriert | Auf Job-Ebene gesetzt | Auf Step-Ebene verschieben |
| Action nicht gefunden | Kurzform-URL ohne Registry-Konfiguration | Vollqualifizierte URL verwenden |
| Runner ohne SSH, Docker etc. | Standard-Image ist minimal | `apt-get install -y <package>` in einem Step |
| Actions-Tab fehlt komplett | Für das Repo nicht aktiviert | Einstellungen → Units → Actions aktivieren |
| Secret im Workflow nicht zugänglich | Falscher Scope (env vs. repo) | Sicherstellen, dass es ein Repo- oder Org-Secret ist |
| GitHub-only Action schlägt in Air-Gapped-Env fehl | Runner kann github.com nicht erreichen | Action auf Ihre Forgejo-Instanz spiegeln |
| `github.*` Kontext funktioniert nicht | Veraltete Forgejo-Version | Update durchführen oder `forgejo.*` / `forge.*` Aliase nutzen |

---

## Fazit

Codeberg ist sinnvoll, wenn Sie digitale Souveränität, DSGVO-Konformität oder Unabhängigkeit vom Platform-Lock-in benötigen. Der Kompromiss ist ein kleineres Ökosystem und ausführlichere Workflow-Dateien.

Die wichtigsten Erkenntnisse: Verwenden Sie immer vollqualifizierte Action-URLs, setzen Sie Timeouts und Berechtigungen auf der Step-Ebene und rechnen Sie mit einem minimalen Runner-Image, das eine explizite Tool-Installation erfordert. Sobald man diese drei Regeln verinnerlicht hat, ist die Migration von GitHub Actions zu Forgejo Actions unkompliziert.

Wenn Ihr Team GitHub Actions bereits kennt, bemisst sich die Lernkurve in Stunden, nicht in Tagen. Die tea CLI füllt die Lücke, die `gh` hinterlässt, und die Workflow-Syntax ist so ähnlich, dass das Muskelgedächtnis größtenteils übernommen werden kann. Achten Sie nur auf die Fallstricke auf der Job-Ebene.