Zum Hauptinhalt springen

Fehlerbehebung

Häufige Probleme und ihre Lösungen. Jeder Abschnitt verweist für mehr Hintergrund auf die passende Referenzseite.

Authentifizierung und Anmeldung

E-Mail zum Zurücksetzen des Passworts kommt nicht an

Sieh in deinem Spam-Ordner nach. E-Mails zum Zurücksetzen des Passworts kommen von hello@frem.sh. Nutzt deine Organisation SSO, ist das Zurücksetzen des Passworts nicht der richtige Weg. Verwende stattdessen den Button Anmelden mit <IdP> auf der Anmeldeseite. SSO-Konten haben möglicherweise gar kein lokales Passwort.

SSO-Anmeldung schlägt mit redirect_uri mismatch fehl

Der IdP hat den Callback abgelehnt, weil die dort registrierte Redirect-URI nicht genau mit dem übereinstimmt, was fremforge sendet. Die Redirect-URI lautet https://frem.sh/user/oauth2/<auth-source-name>/callback, wobei <auth-source-name> der genaue Name der Auth-Quelle ist, wie er auf ihrer Karte unter Organisationsverwaltung → SSO steht; kopiere diesen Namen, statt ihn abzutippen. Schon ein einzelner abschließender Schrägstrich zu viel oder zu wenig löst diesen Fehler aus. Siehe OIDC-Single-Sign-On.

SSH: Permission denied (publickey)

Drei häufige Ursachen:

  • Der Schlüssel wurde deinem fremforge-Konto nicht hinzugefügt (Benutzereinstellungen → SSH- / GPG-Schlüssel → Schlüssel hinzufügen).
  • Die Schlüsseldatei, auf die dein SSH-Client verweist, gehört zu einem anderen Benutzerkonto.
  • Das Schlüsselformat wird nicht unterstützt (Ed25519, RSA 3072+ und ECDSA werden unterstützt; DSA-Schlüssel werden abgelehnt).

Teste deinen Schlüssel: ssh -T -p 443 git@ssh.frem.sh. fremforge stellt SSH auf Port 443 über ssh.frem.sh bereit (Port 22 ist nicht offen). Eine erfolgreiche Authentifizierung liefert Hi <username>! You've successfully authenticated.... Siehe Erste Schritte für die Einrichtung der Schlüssel und Verbinden für den Host-Alias in ~/.ssh/config, mit dem du in deinen Remotes weiterhin git@frem.sh schreiben kannst.

PAT abgelaufen / 401 bei API-Aufrufen

PATs laufen nach 90 Tagen ab, das ist zugleich das Maximum (ttl_days akzeptiert 1-90). Prüfe:

  1. Das Token steht noch unter Benutzereinstellungen → Git-Zugriffstoken.
  2. Das Token hat den nötigen Scope. REST-Aufrufe an die Steuerungsebene verwenden das Scope-Vokabular von fremforge (orgs:read, findings:read, …) – siehe API-Token. Paket-Registries nehmen überhaupt kein PAT an; siehe Pakete / Registry weiter unten.
  3. Der Wert des Tokens wurde korrekt kopiert (er wird nur einmal beim Erstellen angezeigt).

Erzeuge im Zweifel ein neues Token.

CI / Runner

Job hängt in der Warteschlange

Der Organisation sind 2 gleichzeitige Jobs pro Nutzer (mindestens 10, höchstens 60) garantiert, und sie kann bis zu 60 nutzen, solange die Plattform freie Kapazität hat. Eine Organisation im Testzeitraum führt 2 gleichzeitig aus. Wie viele Jobs gerade laufen, siehst du unter frem.sh/<org>/_admin/billing. Sind alle Slots der Organisation belegt, warten Jobs in der Warteschlange, bis ein Slot frei wird. Sie werden nicht abgebrochen.

Ist die Warteschlange leer und hängen Jobs trotzdem, ist der Runner-Agent möglicherweise offline. Prüfe den Runner-Status in den Forgejo-Einstellungen der Organisation unter Einstellungen → Actions → Runner (frem.sh/org/<org>/settings/actions/runners).

actions/checkout schlägt fehl: repository not found

Das eingebaute FORGEJO_TOKEN braucht die Berechtigung contents: read. Füge dem Job oder Workflow einen permissions:-Block hinzu:

permissions:
  contents: read

Ist das Repository privat und das Token ein PAT statt des eingebauten Tokens, prüfe, ob das PAT den Scope repo hat.

Secret ist gesetzt, aber im Job leer

Das Secret ist auf der falschen Ebene gesetzt. Secrets haben diese Rangfolge: Umgebungs-Secret → Repository-Secret → Organisations-Secret. Deklariert dein Job environment: production, werden nur Secrets eingespielt, die auf dieser Umgebung gesetzt sind (sowie Repository- und Organisations-Secrets, die nicht von ihr überdeckt werden). Prüfe, ob das Secret auf der Ebene gesetzt ist, die zur environment:-Deklaration des Jobs passt.

Docker: Cannot connect to the Docker daemon

fremforge-Runner sind kurzlebige VMs, eine pro Commit (debian 13), mit einem vorinstallierten nativen Docker-Daemon. docker build, docker run und docker/build-push-action@v5 funktionieren ohne zusätzliche Einrichtung. Siehst du diesen Fehler, prüfe, ob der Job runs-on: fremforge deklariert (damit er auf einem fremforge-Runner landet und nicht auf einem selbst gehosteten Label ohne Docker):

jobs:
  build-image:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: registry.example.com/${{ github.repository }}:${{ github.sha }}

Zum reinen Kopieren, Umtaggen und Pushen von Images zwischen Registries ist skopeo vorinstalliert. Siehe CI-Runner für die verfügbaren Runner-Labels und docs.frem.sh/de/build/actions/runner-image/ für die vollständige Liste der vorinstallierten Werkzeuge.

upload-artifact wiederholt bei 413 und schlägt dann mit Status Code: 413 fehl

Das Kontingent der Organisation für Actions-Artefakte (5 GiB pro Nutzer) ist voll. Das Log des Schritts zeigt mehrmals A 413 status code has been received, will attempt to retry the upload, dann Status Code: 413 und Status Message: Request Entity Too Large. Den Job zu wiederholen hilft nichts, solange kein Platz frei wird. Siehe Actions-Artefakte und -Anhänge.

Action not found: uses: some/action@v1

Die meisten Actions aus dem GitHub Marketplace funktionieren auf fremforge. Actions, die github.com/api/v3 direkt aufrufen, schlagen fehl, weil sie die GitHub-API ansprechen und nicht die fremforge-API. Die Kompatibilitätsmatrix pro Action steht unter Marketplace-Kompatibilität.

Git und Repositorys

Push abgelehnt: Secret erkannt

Gitleaks (Pre-Receive-Hook) hat den Push blockiert, weil im Commit ein Secret-Muster erkannt wurde. Der Push wurde nicht angenommen. Das Secret hat das Repository nie erreicht.

So behebst du es:

  1. Rotiere das Secret sofort in dem System, das es ausgestellt hat, auch wenn der Push abgelehnt wurde. Geh davon aus, dass der Wert kompromittiert ist, seit er in deinem Arbeitsbaum aufgetaucht ist.
  2. Entferne das Secret mit git filter-repo aus deinem Arbeitsbaum und aus dem Commit-Verlauf.
  3. Pushe den bereinigten Verlauf erneut.

Welche Muster erkannt werden, steht unter Sicherheit und Lieferkette.

Push abgelehnt: Branch-Schutz

Eine Branch-Schutzregel blockiert den Push. Prüfe die Regeln unter Repository → Einstellungen → Branches → <branch name>. Häufige Ursachen: Eine erforderliche Statusprüfung ist nicht bestanden, Force-Push ist deaktiviert, oder der Push verlangt einen signierten Commit.

LFS: batch request failed

Git LFS steht in jedem Repository zur Verfügung; es gibt keinen Schalter pro Repository, den du einschalten müsstest. Repository → Einstellungen → LFS listet die LFS-Dateien, die das Repository bereits speichert. Besteht der Fehler weiter, prüfe das Speicherkontingent der Organisation. LFS-Speicher zählt zum LFS-Pool von 5 GB pro Nutzer, der vom Pool der Paket-Registry (5 GB pro Nutzer) getrennt ist.

Webhooks

Webhook wird nicht ausgelöst

Prüfe die letzten Zustellversuche unter Repository → Einstellungen → Webhooks → <webhook> → Letzte Zustellungen. Die häufigste Ursache ist, dass die Payload-URL von den Egress-IPs von fremforge in T Cloud Public aus nicht erreichbar ist. Werden Zustellungen als fehlgeschlagen angezeigt, enthält der Antwortkörper meist den HTTP-Status, den dein Endpunkt zurückgegeben hat. Die Egress-IP-Bereiche stehen unter Webhooks.

Webhook wird ausgelöst, aber die Payload stimmt nicht

Prüfe, welche Ereignistypen abonniert sind. Ein Push auf ein Tag sendet ein push-Ereignis, kein create-Ereignis. Sieh dir die Konfiguration unter Events am Webhook an. Das vollständige Ereignisvokabular steht unter Webhooks.

SSO / SCIM

Per SCIM bereitgestellter Nutzer kann sich nicht anmelden

Bevor sich per SCIM bereitgestellte Nutzer authentifizieren können, muss die Domain verifiziert sein. Verifiziere die E-Mail-Domain unter Organisationsverwaltung → SSO → Verifizierte Domains. Die Domain aus der E-Mail-Adresse des Nutzers muss dort stehen.

Pakete / Registry

Registries akzeptieren nur zwei Arten von Zugangsdaten: das automatische Token eines Forgejo-Actions-Jobs und das kurzlebige Token, das die fremforge-CLI deinen Werkzeugen übergibt. API-Tokens (ffp_…) werden abgelehnt. Siehe Paket-Registry → Authentifizierung.

Actions-Job: 403 this job's token can only write packages linked to its own repository

Der Job wollte ein Paket veröffentlichen, das zu einem anderen Repository der Organisation gehört oder mit keinem Repository verknüpft ist. Das Token eines Jobs schreibt nur Pakete, die mit seinem eigenen Repository verknüpft sind, und neue Pakete, die er selbst anlegt. Veröffentliche aus dem Repository, zu dem das Paket gehört, oder verknüpfe ein nicht verknüpftes Paket auf der Seite Einstellungen des Pakets mit diesem Repository.

Actions-Job: 401 oder 403 beim Veröffentlichen aus einem Pull Request

Läufe für Pull Requests aus Forks bekommen nur Lesezugriff. Veröffentliche aus einem Push- oder Tag-Workflow im Repository selbst.

docker pull oder push: unauthorized

Prüfe auf deinem Rechner die Anmeldung der CLI und den Helper:

fremforge auth status
printf 'frem.sh\n' | docker-credential-fremforge get    # prints JSON when the helper works
  • not logged in → führe fremforge auth login aus.
  • docker-credential-fremforge: command not found → das Verzeichnis des Helpers (~/.local/bin) ist nicht in deinem PATH, oder fremforge auth configure docker wurde nie ausgeführt.
  • fremforge manages frem.sh registry credentials nach docker login frem.sh → das ist erwartet; der Helper lehnt gespeicherte Passwörter ab. Verwende fremforge auth login.

npm, Maven oder Gradle: 401 nach einer Weile

Diese Werkzeuge lesen eine Kopie des Tokens aus ihrer Konfigurationsdatei, und diese Kopie läuft nach höchstens einer Stunde ab. Führe einen beliebigen fremforge-Befehl oder fremforge auth refresh aus, um sie neu zu schreiben. Füge "preinstall": "fremforge auth refresh --quiet" zu package.json hinzu oder einen Schritt vor dem Build in deiner IDE, damit Builds immer mit einem frischen Token starten.

pip oder uv: 401 oder eine Passwortabfrage

pip und uv fragen keyring nur, wenn man es ihnen sagt: pip config set global.keyring-provider subprocess oder UV_KEYRING_PROVIDER=subprocess für uv. Die Index-URL muss deinen Benutzernamen enthalten (https://<username>@frem.sh/api/packages/<org>/pypi/simple/). Prüfe, ob das keyring in ~/.local/bin in deinem PATH zuerst kommt: command -v keyring.

Verfügbarkeit von Organisations-Slug und -Name

Organisations-Slugs müssen 3-30 Zeichen lang sein, kleingeschrieben, nur Buchstaben, Ziffern und Bindestriche, ohne Bindestrich am Anfang oder Ende.

Wird ein Slug bei der Registrierung als nicht verfügbar angezeigt, ist er entweder von einer anderen Organisation registriert oder steht auf der Liste reservierter Namen. Die reservierte Liste umfasst gängige Rollennamen (admin, api, billing, support, status, security, abuse, root, system, fremforge und ähnliche), um Phishing und Kollisionen mit Dienstpfaden zu verhindern.

Markennahe Namen (etwa Slugs, die bekannten Markennamen stark ähneln) kommen in eine weiche Prüfwarteschlange, statt sofort blockiert zu werden. Ist deine Registrierung in der Warteschlange, bekommst du innerhalb eines Geschäftstags eine E-Mail von support@frem.sh. In den meisten Fällen werden seriöse Unternehmen, die ihren eigenen Markennamen verwenden, ohne Umstände freigegeben.

Ist dein gewünschter Slug von einer inaktiven oder ihn blockierenden Organisation belegt, wende dich an support@frem.sh. Gib den gewünschten Slug und die Domain deiner Organisation oder einen anderen Nachweis der Inhaberschaft an. Übertragungen von Slugs werden im Einzelfall entschieden.

Den Slug deiner Organisation nach dem Anlegen ändern: Organisationsverwaltung → Einstellungen → Organisation umbenennen. Alle bestehenden Repository-URLs, Clone-URLs und API-Aufrufe mit dem alten Slug werden 90 Tage lang weitergeleitet. Nach 90 Tagen kann der alte Slug wieder registriert werden.

Querverweise