CI-runners

fremforge biedt gehoste runners die bij elk abonnement per gebruiker zijn inbegrepen, en ondersteunt eigen runners (BYO) voor teams die on-premises, eigen hardware of een specifieke plek in het netwerk nodig hebben. Beide typen runners voeren workflows van Forgejo Actions uit met dezelfde YAML-syntaxis als GitHub Actions.

Gehoste runners

Gehoste runners zijn virtuele machines per commit op T Cloud Public in de regio eu-de (Biere/Magdeburg). Een VM wordt ingericht vanuit een eigen debian-image met Docker vooraf geïnstalleerd, voert de jobs van één commit van één repository uit en wordt verwijderd zodra de jobs van die commit klaar zijn. Er blijft niets bewaard tussen commits.

Beschikbare labels

Verwijs in je workflow naar een label:

jobs:
  build:
    runs-on: fremforge

Containerbuilds werken direct op twee manieren; zie Inhoud van de runner-image § Containerbuilds hieronder voor de volledige uitsplitsing:

• Native Docker (standaard): docker build, docker compose en docker pull werken gewoon. De Docker-daemon draait native op de VM (geen Docker-in-Docker-sidecar), dus docker gedraagt zich hetzelfde als op een door GitHub gehoste runner. Geschikt voor 90% van de workflows.
• kaniko: zonder daemon, snellere koude start, betere laagcache bij externe registries. Gebruik dit als je geen BuildKit-specifieke functies nodig hebt.

jobs:
  build-image:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t registry.example.com/$GITHUB_REPOSITORY:$GITHUB_SHA .
      - run: docker push registry.example.com/$GITHUB_REPOSITORY:$GITHUB_SHA 2>&1 | stdbuf -oL tr '\r' '\n' | grep -vE '^(Waiting|)$'

Gehoste ARM64-runners en extra OS-varianten (Ubuntu, Fedora, …) staan op de roadmap (zie de changelog); fremforge richt zich op dit moment alleen op x86_64 Linux. Eigen runners (zie hieronder) zijn in de tussentijd de route voor ARM64- of niet-Linux-workflows.

Isolatiemodel

Jobs draaien op eigen virtuele machines met een eigen kernel. Het platform houdt de wachtrij van Forgejo Actions in de gaten en start voor een wachtende job een nieuwe VM. Een koude start duurt ongeveer 40 seconden tot de eerste stap van de job; er is geen pool met vooraf gestarte VM’s.

Eén commit, één vertrouwensdomein. Een VM voert alleen jobs uit van de commit en repository waarvoor hij is gestart. Als een job klaar is, wacht de VM tot 60 seconden op een andere job van dezelfde commit, in welke workflow dan ook, en voert die uit zonder opnieuw op te starten (ongeveer 5 seconden tot de start). Daarna schakelt hij uit en wordt hij verwijderd. Geen enkele VM voert jobs uit van twee commits, twee repository’s of twee organisaties, dus beschouw alle jobs van één commit als één vertrouwensdomein. Inloggegevens die het platform kent (Docker- en npm-logins, de gebruikelijke credentialbestanden), worden tussen jobs gewist, maar toolcaches en opgehaalde images blijven op de VM staan. Zie Beveiligingsmodel van de gehoste runners voor het volledige ontwerp.

Jobs dimensioneren voor gehoste runners

Elke nieuwe VM kost ongeveer 40 seconden opstarttijd vóór je eerste stap, en vaak de wachttijd van 60 seconden na je laatste. Een job die 15 seconden werk doet, houdt een VM dus ongeveer twee minuten bezet. Daarom:

• Geef een job alleen een eigen VM als het werk ongeveer 2 minuten of langer duurt. Kortere checks (lint, een kleine testsuite, een controlescript) zijn goedkoper en sneller als extra stappen in een bestaande job.
• Verdeel lang, onafhankelijk werk (testshards, imagebuilds, end-to-end-suites) over jobs. Daar is gelijktijdigheid voor.
• Verdeel kort werk binnen één job in plaats van over jobs, bijvoorbeeld meerdere tofu plan-runs als achtergrondprocessen in één stap. Die wachten vooral op API’s, niet op de CPU.
• Ketens hergebruiken VM’s automatisch. Een needs:-job die klaar is om te starten terwijl de VM van zijn voorganger nog wacht (binnen 60 seconden), draait zonder opstarten op die VM. Een brede uitwaaiering van jobs die allemaal tegelijk starten, kan niets hergebruiken: elke job heeft een eigen VM nodig.
• Houd een run binnen je gelijktijdigheid. Een matrix die breder is dan het gegarandeerde aandeel van je organisatie, draait in golven, en de laatste golf wacht tot een hele job klaar is. Dimensioneer shards zo dat een run in één golf past.

Geheugen

Een VM van een gehoste runner heeft 4 GiB geheugen en geen swap (2 vCPU). Er is op dit moment geen grotere gehoste runner.

Een job die zonder geheugen komt te zitten, faalt binnen ongeveer een minuut. Zakt het beschikbare geheugen onder ongeveer 4% (zo’n 130 MiB), dan stopt de runner het grootste proces van de job, bij voorkeur buildtools zoals node, tsc, java en vitest-workers. Hij stuurt eerst SIGTERM, en SIGKILL als het geheugen blijft dalen. De stap faalt met exitcode 143 of 137, en het log van de stap zegt waarom:

earlyoom: killed node (pid 4242) because the runner VM ran out of memory. ...

De runner zelf is nooit het proces dat wordt gestopt, dus het resultaat en de logs van de job worden nog steeds gemeld. Vóór deze wijziging kon een job die te groot werd voor de VM ongemerkt blijven hangen tot zijn timeout-minutes.

Zie je deze regel, verlaag dan het piekgeheugen van de job:

• Verdeel het werk over jobs. Een grote build naast zijn integratietests draaien, of een docker build naast testcontainers, telt de twee pieken op één VM bij elkaar op.
• Begrens het geheugen van de tool. Bijvoorbeeld NODE_OPTIONS=--max-old-space-size=2048 voor Node, --checkers 1 en GOMEMLIMIT voor TypeScript 7 (tsc geschreven in Go), -Xmx voor Java, minder testworkers (--maxWorkers / --pool-options).
• Stream in plaats van in te laden. Zie voor grote imagescans Grote images scannen met Trivy.

Past een job niet in 4 GiB, neem dan contact op met support@frem.sh, of draai hem op een eigen runner die er groot genoeg voor is.

Inbegrepen minuten en gelijktijdigheid

Jobs boven de limiet van je organisatie wachten in de wachtrij in plaats van te falen. Neem contact op met support@frem.sh als je een hoger gegarandeerd aandeel nodig hebt.

Facturatie van overschrijding (optioneel): standaard komen nieuwe jobs in de wachtrij als de pool op is. Eigenaren van de organisatie kunnen gemeten overschrijding inschakelen via Organisatiebeheer → Facturatie → Verbruik van runner-minuten. Staat dat aan, dan worden minuten boven de pool op de volgende factuur in rekening gebracht tegen € 0,01 per minuut. Overschrijding kan op dezelfde pagina op elk moment weer worden uitgeschakeld.

Verbruiksdashboard

Volg het verbruik van runnerminuten via Organisatiebeheer → Facturatie → Verbruik van runner-minuten.

Het verbruiksdashboard toont:

Minuten worden geteld van de start tot het einde van de job, naar boven afgerond op de seconde. Wachttijd in de wachtrij (wachten op een runner) telt niet mee.

De maandperiode wordt op de 1e van elke maand (UTC) gereset. Ongebruikte minuten worden niet meegenomen.

Minuten van eigen runners worden apart bijgehouden in hetzelfde dashboard en tellen niet mee voor de gehoste pool.

Drempels voor verbruiksmeldingen die je zelf kunt instellen, zijn nog niet beschikbaar: fremforge stuurt standaard een waarschuwingsmail wanneer de organisatie 80% van de maandelijkse pool bereikt. Neem contact op met support@frem.sh om de drempel aan te passen.

Inhoud van de runner-image

De gehoste runner-image wordt wekelijks (ma 06:00 UTC) opnieuw gebouwd vanuit de upstream-versies van tools die Renovate volgt. Elke download tijdens de build is vastgezet met sha256 (de build faalt bij afwijkingen). Tijdens de build draait een CVE-poort van Trivy: een image met HIGH- of CRITICAL-bevindingen wordt tegengehouden totdat hij is gepatcht.

Voordat een opnieuw gebouwde image live gaat op de runnervloot, wordt hij nogmaals gecontroleerd tegen de lijsten met actief uitgebuite kwetsbaarheden (ENISA EUVD en CISA KEV). Een image met een actief uitgebuite CVE waarvoor een oplossing beschikbaar is, wordt ongeacht de ernst niet uitgerold, tenzij een beoordeelde uitzondering van maximaal 30 dagen die CVE dekt. Runners blijven de vorige image gebruiken totdat er een gepatchte is gebouwd.

Model met twee lagen, beide in de EU:

• Systeemlaag (~300 MB): debian-basis + systeemtools in één versie (Node 24 LTS, build essentials, scanners, IaC- en cloud-CLI’s, browsers, databaseclients). Onderdeel van de opstartschijf van de VM; geen download per job.
• hostedtoolcache-laag (~7 GB): taaltoolchains in meerdere versies (Node, Go, Python, .NET, Java, Ruby) + Android SDK + Miniconda3 + R (sinds 2026-06-06). Ingebakken in dezelfde opstartschijf van de VM op /opt/hostedtoolcache. setup-*-actions halen hun versie hier vandaan, zonder download per job.

Hoe we volledige dekking leveren in ~7 GB in totaal, terwijl ubuntu-latest van GitHub ~50 GB is: zie het verhaal over de grootte hieronder.

Vooraf geïnstalleerd in de systeemlaag:

Vooraf geïnstalleerd in de hostedtoolcache (opgehaald door setup-*-actions, zonder download per job):

De officiële versielijst met de exacte versies + image-digest + samenvatting van de Trivy-scan + CycloneDX-SBOM wordt bij elke wekelijkse herbouw gepubliceerd; zie de referentie van de runner-image voor de actuele toolstack.

Containerbuilds: native Docker of kaniko

Twee routes; kies op basis van de workload:

Native Docker (standaard): de VM wordt geleverd met de Docker-daemon geïnstalleerd en draaiend op de host. Je docker-CLI praat ermee via de standaard lokale socket: geen omweg via DOCKER_HOST, geen sidecar. Werkt voor docker build, docker compose, docker pull, multi-stage builds en BuildKit-functies. Een directe vervanging voor docker op de door GitHub gehoste runners.

- run: docker build -t myapp:${{ github.sha }} .
- run: docker push myapp:${{ github.sha }} 2>&1 | stdbuf -oL tr '\r' '\n' | grep -vE '^(Waiting|)$'

Grote images scannen met Trivy

trivy image <ref> (via de daemon) houdt de laagmetadata van de hele image in het geheugen terwijl het het bestandssysteem doorloopt; images van meerdere GB kunnen ruim boven de geheugenlimiet van de runner-VM uitpieken en midden in de scan een OOM-kill veroorzaken. Het betrouwbare patroon voor elke imagegrootte is de image te streamen via docker save:

- run: docker build -t myapp:${{ github.sha }} .
- run: |
    docker save myapp:${{ github.sha }} | trivy image \
      --severity HIGH,CRITICAL --ignore-unfixed \
      --scanners vuln --pkg-types os \
      --offline-scan --no-progress --quiet \
      --input -

Waarom het werkt: docker save leest de lagen van schijf en streamt de tarball laag voor laag naar de stdin van trivy. Trivy leest uit elke laag de metadata van de OS-pakketten (~tientallen KB per laag) en gooit die weg vóór de volgende laag. Het gezamenlijke piek-RSS blijft rond de 500 MB, ongeacht de totale grootte van de image, dus de scan past ruim binnen het geheugenbudget van de runner-VM. GOGC=10 vóór trivy (bijv. GOGC=10 trivy ...) maakt de heap nog krapper als je ooit dicht bij de limiet komt.

Het filter tr '\r' '\n' op docker push wordt aanbevolen: Docker schrijft de voortgang van het uploaden van lagen met carriage returns die de regel overschrijven, en het staplog van Forgejo Actions behandelt dat als één steeds groeiende regel die ongemerkt wordt afgekapt. Zonder het filter toont een push die halverwege blijft hangen of een fout geeft, in het log alleen <layer>: Preparing zonder details over de fout; tegen de tijd dat de stap een time-out krijgt, is de eigenlijke fout overschreven. Door via tr te pipen wordt elke voortgangsstap een eigen regel die volledig wordt vastgelegd, en grep -vE '^(Waiting|)$' haalt lege en inactieve opvulregels weg. De doorvoer van het pushen van lagen verandert niet.

Registries van klanten (ghcr.io, dockerhub, quay.io, je eigen) zijn bereikbaar via de egress van de runner; de proxy heeft een time-out van 30 minuten per verzoek, zodat PUT’s van lagen van meerdere GB netjes afronden. Budget voor de imagegrootte: 50 GB per build (de limiet van de scratch-schijf van de VM); dien een ticket in als je meer nodig hebt.

kaniko: OCI-bouwer zonder daemon en zonder root. Snellere koude start dan de volledige Docker-daemon, en gaat beter om met de laagcache bij externe registries. Gebruik dit als de build geen BuildKit-specifieke functies nodig heeft.

- run: |
    /usr/local/bin/kaniko \
      --context=$GITHUB_WORKSPACE \
      --dockerfile=Dockerfile \
      --destination=registry.example.com/$GITHUB_REPOSITORY:$GITHUB_SHA

Voeg voor kind- / testcontainers-workloads die KVM-geneste gasten nodig hebben, het label dind-privileged toe aan runs-on. fremforge stuurt deze naar een VM-type met geneste virtualisatie.

De grootte vergeleken met GitHub

ubuntu-latest van GitHub is ~50 GB omdat het het volgende inbakt:

• Meerdere versies per taal: 3 recente reeksen voor Node, Python, Java en Ruby; 2 voor Go en .NET (~3 GB in totaal). De tabel hierboven is de gezaghebbende set.
• Android SDK + NDK (~10 GB bij GitHub): wij bakken de kern-SDK in (platform 34 + build-tools + platform-tools, ~3 GB); extra API-niveaus + NDK + emulators installeer je per job via setup-android@v3 (geen nieuwe download van wat al is ingebakken).
• Vooraf opgehaalde Docker-images voor servicecontainers (postgres, mysql, mongo, redis, mssql ~5 GB): niet ingebakken; een docker pull haalt ze op van Docker Hub, of via de dependency-proxy van je organisatie (zie pakketcaches).
• De browser Microsoft Edge: niet ingebakken (Chromium is voor headless tests in CI dezelfde engine).
• Mono / Julia / Swift / Haskell / Lua / Crystal / Nim / Elixir: niet ingebakken (niche, per job te installeren via setup-* of apt).
• Meerdere GCC-versies, oude toolchains die voor compatibiliteit worden bewaard: wij leveren één actuele set.

We missen geen tools die de gewone workflow gebruikt: elke gangbare taal, elke grote cloud-CLI, elke gangbare scanner, beide grote browsers, Docker (native, root via het label dind-privileged), Android (kern-SDK) en datawetenschap (Miniconda3 + R). iOS / Xcode werkt niet op Linux en wordt apart gevolgd; nichetalen (Julia/Swift/Haskell/Mono) installeer je per job. Laat het ons weten als je team iets nodig heeft wat we niet inbakken, dan bekijken we het voor de volgende wekelijkse herbouw van de image.

Zie voor alle details per tool docs.frem.sh/build/actions/runner-image/.

Eigen runners (BYO)

Registreer je eigen runners bij elke fremforge-organisatie (on-premises servers, cloud-VM’s, Mac minis, Raspberry Pi’s). Minuten van eigen runners tellen niet mee voor de gehoste pool.

Registratie

1. Ga in de Forgejo-instellingen van de organisatie naar Instellingen → Actions → Runners → Nieuwe runner aanmaken (frem.sh/org/<org>/settings/actions/runners).
2. Kopieer het registratietoken.
3. Download het binary van de Forgejo-runner. De actuele stabiele release wordt gepubliceerd op code.forgejo.org/forgejo/runner/releases; zet bij de installatie een recente tag vast:

# Linux x86_64 — replace <version> with the tag from the releases page (e.g. v6.4.0)
curl -sSL https://code.forgejo.org/forgejo/runner/releases/download/<version>/forgejo-runner-<version>-linux-amd64 \
  -o forgejo-runner && chmod +x forgejo-runner

# macOS arm64
curl -sSL https://code.forgejo.org/forgejo/runner/releases/download/<version>/forgejo-runner-<version>-darwin-arm64 \
  -o forgejo-runner && chmod +x forgejo-runner

fremforge volgt de actuele releases van Forgejo; runners met oudere binaries blijven werken, maar horen binnen één releasecyclus te worden bijgewerkt om CVE-patches mee te krijgen.

4. Registreer de runner:

./forgejo-runner register \
  --instance https://frem.sh \
  --token <registration-token> \
  --name my-runner \
  --labels linux,self-hosted,my-custom-label

5. Start de runner:

./forgejo-runner daemon

Ondersteunde platforms

Eigen labels

De labels die je bij de registratie toekent, zijn waar je in runs-on: naar verwijst:

jobs:
  deploy:
    runs-on: [self-hosted, my-custom-label]

Meerdere labels in een lijst betekenen “zoek een runner die AL deze labels heeft”. Het label self-hosted is een conventie. Neem het op om te voorkomen dat een job voor een eigen runner per ongeluk naar een gehoste runner gaat.

Gebruik geen gereserveerde labels. De labels fremforge en linux/amd64 gaan naar onze pool met gehoste runners (de oudere aliassen fremforge-cci en cci zijn verouderd en gaan dezelfde kant op). Kies voor je eigen runners afwijkende labels (bijv. self-hosted, on-prem, my-team-runner), zodat workflows ze ondubbelzinnig kunnen aanspreken.

Netwerkeisen voor de runnerhost

Het runnerbinary opent long-poll-HTTPS-verbindingen naar https://frem.sh en kloont repository’s via HTTPS. Vanuit de host gezien zijn dit de eisen aan de verbinding:

Er is geen inkomende verbinding nodig: de runner zet alle verbindingen zelf naar buiten op. Een runner achter NAT of een firewall werkt prima, zolang hij frem.sh:443 kan bereiken.

Verantwoordelijkheid voor beveiliging en isolatie

Bij gehoste runners zorgt fremforge voor isolatie op kernelniveau tussen commits en tussen klanten (elke commit draait in een nieuwe, tijdelijke ECS-VM; jobs van dezelfde commit kunnen die delen). Bij eigen runners ben je zelf verantwoordelijk voor de isolatie. Een zelf gehoste runner die workflows uit meerdere repository’s afhandelt, deelt toestand tussen jobs, tenzij je elke runner beperkt tot één repository of organisatie.

Draai je workflows van meerdere teams of vertrouwensdomeinen, behandel je eigen runner dan zoals zelf gehoste runners van GitHub Actions worden behandeld:

• Eén runner per repository (of per vertrouwensgrens) als secrets gevoelig zijn.
• Registreer geen eigen runner bij een openbare repository: iedereen met merge-rechten zou een workflowwijziging kunnen doorvoeren die willekeurige code op je runnerhost uitvoert.
• Behandel de runnerhost als productie: verhard het besturingssysteem, houd het runnerbinary gepatcht en leid het uitgaande verkeer door je eigen SSRF- / egresscontroles.

De SSRF-proxy voor uitgaand verkeer van fremforge geldt NIET voor eigen runners, alleen voor gehoste runners. Het netwerkbeleid van je runner is wat je zelf op de host inricht.

Egress en netwerk

Egress-allowlist op organisatieniveau: neem contact op met support@frem.sh om runnerjobs uitgaande toegang te geven tot extra CIDR’s of poorten. Egressregels worden op platformniveau ingesteld.

De SSRF-proxy is een ondergrens van het platform. Hij kan niet worden uitgeschakeld. Hij voorkomt dat runnerjobs de instance-metadata van T Cloud Public of interne infrastructuur bereiken.

Secrets in jobs

Secrets worden als omgevingsvariabelen geïnjecteerd en in joblogs gemaskeerd. Elke logregel met de waarde van een secret wordt vervangen door ***.

Syntaxis om ernaar te verwijzen:

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.MY_API_KEY }}
    run: ./deploy.sh

Bereiken van secrets

Voor secrets van een omgeving moet de job een omgeving declareren:

jobs:
  deploy:
    runs-on: fremforge
    environment: production
    steps:
      - run: echo ${{ secrets.PROD_API_KEY }}

Gebruik voor inloggegevens van cloudproviders bij voorkeur OIDC-tokenfederatie in plaats van langlevende secrets. Geen secret om op te slaan, geen secret om te roteren.

Problemen oplossen

Een stap faalt met earlyoom: killed <process> ... ran out of memory.

De job gebruikte meer dan de 4 GiB geheugen van de runner-VM, dus de runner stopte het grootste proces in plaats van de VM te laten vastlopen. Zie Geheugen voor hoe je de piek van de job verlaagt.

Een job blijft in de wachtrij hangen.

De meest voorkomende oorzaak is dat de limiet voor gelijktijdigheid per organisatie is bereikt (2 gelijktijdige jobs per gebruiker gegarandeerd, minimaal 10 en maximaal 60; zie Inbegrepen minuten en gelijktijdigheid). Bekijk Organisatiebeheer → Facturatie → Verbruik van runner-minuten voor het huidige aantal actieve jobs. Zit je aan de limiet, wacht dan tot een lopende job klaar is of neem contact op met support@frem.sh voor een verhoging via Enterprise-on-Demand.

Het docker-commando werkt, maar een handeling die extra rechten vereist faalt (bijv. een kind-cluster aanmaken met KVM-nesting).

De standaard-VM voor runs-on: fremforge draait Docker native met de standaardinstellingen voor een gebruiker zonder root: docker build / docker compose / docker pull werken direct, maar handelingen die extra capabilities nodig hebben (KVM-nesting, rauwe toegang tot /dev voor een geneste gast, bepaalde netwerkmodi van kind-clusters), niet. Voeg het label dind-privileged toe aan runs-on (runs-on: [fremforge, dind-privileged]): fremforge stuurt de job dan naar een VM-type met geneste virtualisatie. Dezelfde isolatie van één VM per commit; dezelfde image; alleen met verhoogde capabilities.

Voor het puur kopiëren of opnieuw taggen van images tussen registries (zonder build) werkt de vooraf geïnstalleerde skopeo zonder dat de volledige Docker-daemon nodig is.

Een secret wordt in de logs gemaskeerd, maar de stap gedraagt zich alsof het leeg is.

Het secret bestaat in de runtime (de maskering bevestigt dat), maar de waarde op het juiste bereik is niet ingesteld. Controleer:

1. Is het secret ingesteld op het niveau van de organisatie, de repository of de omgeving?
2. Is het een secret van een omgeving: declareert de job dan environment: <name> met de omgeving van het secret?
3. Is de naam van het secret precies goed gespeld (hoofdlettergevoelig)?

De secretsinterface op het betreffende bereik toont de naam van het secret en het tijdstip van de laatste wijziging. Gebruik die om te bevestigen dat het secret bestaat voordat je naar de workflow kijkt.

Zie ook

• OIDC-tokenfederatie: sleutelloze cloudauthenticatie vanuit CI-jobs
• Secrets: secrets van organisaties, repository’s en omgevingen beheren
• Marketplace-compatibiliteit: welke actions uit de GitHub Marketplace op fremforge-runners werken
• AI-houding: welke AI-tools wel en niet in de runneromgeving aanwezig zijn