Naar de hoofdinhoud

Probleemoplossing

Veelvoorkomende problemen en hoe je ze oplost. Elke sectie verwijst naar de relevante naslagpagina voor meer achtergrond.

Authenticatie en aanmelden

E-mail voor wachtwoordherstel komt niet aan

Kijk in je spammap. E-mails voor wachtwoordherstel komen van hello@frem.sh. Gebruikt je organisatie SSO, dan is wachtwoordherstel niet de juiste weg. Gebruik dan de knop Inloggen met <IdP> op de aanmeldpagina. SSO-accounts hebben mogelijk geen lokaal wachtwoord.

SSO-aanmelding faalt met redirect_uri mismatch

De IdP heeft de callback geweigerd omdat de redirect-URI die daar is geregistreerd niet exact overeenkomt met wat fremforge stuurt. De redirect-URI is https://frem.sh/user/oauth2/<auth-source-name>/callback, waarbij <auth-source-name> de exacte Name van de auth-bron is zoals die op de kaart in Organisatiebeheer → SSO staat; kopieer die naam in plaats van hem over te typen. Eén slash meer of minder aan het eind veroorzaakt deze fout al. Zie Single sign-on met OIDC.

SSH: Permission denied (publickey)

Drie veelvoorkomende oorzaken:

  • De sleutel is niet aan je fremforge-account toegevoegd (Gebruikersinstellingen → SSH / GPG sleutels → Sleutel toevoegen).
  • Het sleutelbestand waar je SSH-client naar verwijst, hoort bij een ander gebruikersaccount.
  • Het sleutelformaat wordt niet ondersteund (Ed25519, RSA 3072+ en ECDSA worden ondersteund; DSA-sleutels worden geweigerd).

Test je sleutel: ssh -T -p 443 git@ssh.frem.sh. fremforge biedt SSH aan op poort 443 via ssh.frem.sh (poort 22 is niet open). Een geslaagde authenticatie geeft Hi <username>! You've successfully authenticated... terug. Zie Aan de slag voor het instellen van sleutels en Verbinding maken voor de Host-alias in ~/.ssh/config waarmee je git@frem.sh in je remotes kunt blijven schrijven.

PAT verlopen / 401 bij API-aanroepen

PAT’s verlopen na 90 dagen, en dat is ook het maximum (ttl_days accepteert 1-90). Controleer:

  1. Het token staat nog in de lijst onder Gebruikersinstellingen → Git-toegangstokens.
  2. Het token heeft de vereiste scope. REST-aanroepen naar het controlplane gebruiken het scopevocabulaire van fremforge (orgs:read, findings:read, …); zie API-tokens. Pakketregisters accepteren helemaal geen PAT; zie Pakketten / register hieronder.
  3. De tokenwaarde is correct gekopieerd (ze wordt alleen bij het aanmaken één keer getoond).

Maak bij twijfel een nieuw token aan.

CI / runners

Job blijft in de wachtrij hangen

De organisatie krijgt gegarandeerd 2 gelijktijdige jobs per gebruiker (minstens 10, hoogstens 60), en kan er tot 60 gebruiken zolang het platform capaciteit over heeft. Een organisatie op proef draait er 2 tegelijk. Op frem.sh/<org>/_admin/billing zie je hoeveel jobs er nu draaien. Zijn alle plekken van de organisatie bezet, dan wachten jobs in de wachtrij tot er een vrijkomt. Ze worden niet geannuleerd.

Is de wachtrij leeg maar blijven jobs hangen, dan is de runner-agent mogelijk offline. Controleer de status van de runners in de Forgejo-instellingen van de organisatie onder Instellingen → Actions → Runners (frem.sh/org/<org>/settings/actions/runners).

actions/checkout faalt: repository not found

Het ingebouwde FORGEJO_TOKEN heeft het recht contents: read nodig. Voeg een blok permissions: toe aan de job of workflow:

permissions:
  contents: read

Is de repository privé en is het token een PAT in plaats van het ingebouwde token, controleer dan of de PAT de scope repo heeft.

Secret is ingesteld maar is leeg in de job

Het secret staat op het verkeerde niveau. Secrets volgen deze voorrang: secret van de omgeving → secret van de repository → secret van de organisatie. Declareert je job environment: production, dan worden alleen secrets van die omgeving (en secrets van de repository of organisatie die daardoor niet worden overschaduwd) geïnjecteerd. Controleer of het secret is ingesteld op het niveau dat past bij de declaratie environment: van de job.

Docker: Cannot connect to the Docker daemon

fremforge-runners zijn kortlevende VM’s, één per commit (debian 13), met een native Docker-daemon voorgeïnstalleerd. docker build, docker run en docker/build-push-action@v5 werken allemaal zonder extra instellingen. Zie je deze fout, controleer dan of de job runs-on: fremforge declareert (zodat hij op een fremforge-runner terechtkomt en niet op een zelf gehost label zonder 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 }}

Voor het puur kopiëren, hertaggen of pushen van images tussen registries is skopeo voorgeïnstalleerd. Zie CI-runners voor de beschikbare runnerlabels en docs.frem.sh/build/actions/runner-image/ voor de volledige lijst met voorgeïnstalleerde tooling.

upload-artifact probeert opnieuw bij 413 en faalt dan met Status Code: 413

Het quotum voor Actions-artefacten van de organisatie (5 GiB per gebruiker) is vol. Het steplog toont een paar keer A 413 status code has been received, will attempt to retry the upload, en daarna Status Code: 413 en Status Message: Request Entity Too Large. De job opnieuw uitvoeren helpt pas als er ruimte is vrijgemaakt. Zie Actions-artefacten en bijlagen.

Action niet gevonden: uses: some/action@v1

De meeste actions uit de GitHub Marketplace werken op fremforge. Actions die rechtstreeks github.com/api/v3 aanroepen, falen omdat ze de GitHub-API aanspreken en niet de fremforge-API. Zie Compatibiliteit met de Marketplace voor de compatibiliteitsmatrix per action.

Git en repositories

Push geweigerd: secret gedetecteerd

Gitleaks (pre-receive-hook) heeft de push geblokkeerd omdat er een secretpatroon in de commit is gevonden. De push is niet geaccepteerd. Het secret heeft de repository nooit bereikt.

Zo los je het op:

  1. Roteer het secret meteen in het systeem dat het heeft uitgegeven, ook al is de push geweigerd. Ga ervan uit dat de waarde gecompromitteerd is vanaf het moment dat ze in je werkmap verscheen.
  2. Verwijder het secret uit je werkmap en commitgeschiedenis met git filter-repo.
  3. Push de opgeschoonde geschiedenis opnieuw.

Zie Beveiliging en supply chain voor details over welke patronen worden gedetecteerd.

Push geweigerd: branchbescherming

Een regel voor branchbescherming blokkeert de push. Controleer de regels onder Repo-instellingen → Branches → <branch name>. Veelvoorkomende oorzaken: een vereiste statuscontrole is niet geslaagd, force-push is uitgeschakeld, of de push vereist een ondertekende commit.

LFS: batch request failed

Git LFS is op elke repository beschikbaar; er is geen schakelaar per repository om het aan te zetten. Repo-instellingen → LFS toont de LFS-bestanden die de repository al opslaat. Blijft de fout, controleer dan het opslagquotum van de organisatie. LFS-opslag telt mee voor de LFS-pool van 5 GB per gebruiker, die los staat van de pool van 5 GB per gebruiker voor het pakketregister.

Webhooks

Webhook wordt niet afgevuurd

Controleer de recente afleverpogingen onder Repo-instellingen → Webhooks → <webhook> → Recente bezorgingen. De meest voorkomende oorzaak is dat de payload-URL niet bereikbaar is vanaf de egress-IP’s van fremforge in T Cloud Public. Staan afleveringen als mislukt, dan bevat de body van het antwoord meestal de HTTP-status die je endpoint teruggaf. Zie Webhooks voor de egress-IP-bereiken.

Webhook wordt afgevuurd maar de payload klopt niet

Controleer op welke gebeurtenistypes je bent geabonneerd. Een push naar een tag stuurt een gebeurtenis push, geen gebeurtenis create. Controleer de configuratie Events van de webhook. Zie Webhooks voor het volledige gebeurtenisvocabulaire.

SSO / SCIM

Gebruiker via SCIM ingericht maar kan zich niet aanmelden

Domeinverificatie is vereist voordat gebruikers die via SCIM zijn ingericht zich kunnen authenticeren. Verifieer het e-maildomein onder Organisatiebeheer → SSO → Geverifieerde domeinen. Het domein in het e-mailadres van de gebruiker moet daar staan.

Pakketten / register

Registers accepteren maar twee inloggegevens: het automatische token van een Forgejo Actions-job, en het kortlevende token dat de fremforge-CLI aan je tools geeft. API-tokens (ffp_…) worden geweigerd. Zie Pakketregister → Authenticatie.

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

De job probeerde een pakket te publiceren dat bij een andere repository van de organisatie hoort, of een pakket dat aan geen enkele repository is gekoppeld. Het token van een job schrijft alleen pakketten die aan zijn eigen repository zijn gekoppeld, en nieuwe pakketten die het zelf aanmaakt. Publiceer vanuit de repository waar het pakket bij hoort, of koppel een niet-gekoppeld pakket aan deze repository op de pagina Instellingen van het pakket.

Actions-job: 401 of 403 bij publiceren vanuit een pull request

Runs voor pull requests vanuit forks krijgen alleen leestoegang. Publiceer vanuit een workflow op een push of tag in de repository zelf.

docker pull of push: unauthorized

Controleer op je eigen machine de aanmelding van de CLI en de helper:

fremforge auth status
printf 'frem.sh\n' | docker-credential-fremforge get    # prints JSON when the helper works
  • not logged in → voer fremforge auth login uit.
  • docker-credential-fremforge: command not found → de map van de helper (~/.local/bin) staat niet in je PATH, of fremforge auth configure docker is nooit uitgevoerd.
  • fremforge manages frem.sh registry credentials na docker login frem.sh → dat is de bedoeling; de helper weigert opgeslagen wachtwoorden. Gebruik fremforge auth login.

npm, Maven of Gradle: na een tijdje 401

Deze tools lezen een kopie van het token uit hun configuratiebestand, en die kopie verloopt na hoogstens een uur. Voer een willekeurig fremforge-commando uit, of fremforge auth refresh, om haar te herschrijven. Voeg "preinstall": "fremforge auth refresh --quiet" toe aan package.json, of een stap vóór de build in je IDE, zodat builds altijd met een vers token beginnen.

pip of uv: 401 of een vraag om een wachtwoord

pip en uv vragen keyring alleen als je dat aangeeft: pip config set global.keyring-provider subprocess, of UV_KEYRING_PROVIDER=subprocess voor uv. De index-URL moet je gebruikersnaam bevatten (https://<username>@frem.sh/api/packages/<org>/pypi/simple/). Controleer of de keyring in ~/.local/bin als eerste in je PATH staat: command -v keyring.

Beschikbaarheid van organisatieslugs en -namen

Organisatieslugs moeten 3-30 tekens lang zijn, in kleine letters, alleen letters/cijfers/koppeltekens, zonder koppelteken aan het begin of eind.

Staat een slug bij het aanmelden als niet beschikbaar, dan is hij geregistreerd door een andere organisatie of staat hij op de lijst met gereserveerde namen. Die lijst bevat veelgebruikte rolnamen (admin, api, billing, support, status, security, abuse, root, system, fremforge en vergelijkbare) om phishing en botsingen met servicepaden te voorkomen.

Namen die dicht bij een handelsmerk liggen (bijvoorbeeld slugs die sterk lijken op bekende merknamen), komen in een wachtrij voor lichte beoordeling in plaats van meteen te worden geblokkeerd. Staat je aanmelding in die wachtrij, dan krijg je binnen één werkdag een e-mail van support@frem.sh. In de meeste gevallen worden legitieme bedrijven die hun eigen merknaam gebruiken zonder problemen goedgekeurd.

Is je gewenste slug bezet door een inactieve organisatie of een domeinkaper, neem dan contact op met support@frem.sh. Vermeld de gewenste slug en het domein van je organisatie of ander bewijs van eigendom. Overdrachten van slugs worden per geval behandeld.

De slug van je organisatie na het aanmaken wijzigen: Organisatiebeheer → Instellingen → Organisatie hernoemen. Alle bestaande repository-URL’s, clone-URL’s en API-aanroepen met de oude slug blijven 90 dagen doorverwijzen. Na 90 dagen kan de oude slug weer worden geregistreerd.

Kruisverwijzingen