Migreren van GitLab naar fremforge

Deze gids beschrijft de migratie van GitLab naar fremforge. Hij geldt voor GitLab.com, GitLab self-managed (CE of EE) en GitLab Dedicated. De verschillen tussen die varianten zitten vooral in de manier van authenticeren en in welke GitLab-specifieke functies je hebt aangezet.

Kom je van GitHub, lees dan eerst de gids voor migratie vanaf GitHub. Een aantal voor de hand liggende stappen is identiek en herhalen we hier niet.

Heb je de checklist voor de migratie nog niet uitgevoerd tegen je huidige GitLab-tenant, doe dat dan eerst. Specifiek voor GitLab-migraties signaleert hij include:-verwijzingen naar andere projecten in GitLab CI (die je met de hand moet ontrafelen) en deployments van GitLab Pages (die ergens anders moeten komen te staan, omdat fremforge geen Pages-product heeft; zie stap 6).

Voordat je begint

Wat je zelf nodig hebt:

• Een account met de rol owner op de GitLab-groep(en) die je migreert.
• Een personal access token op GitLab met de scopes api, read_repository, read_user en read_registry.
• Beheerderstoegang tot de fremforge-organisatie waarnaar je migreert.
• Voor de CI-migratie: een overzicht van de GitLab CI-templates, include:-verwijzingen en eventuele eigen GitLab Runner-tags waarvan je pipelines afhankelijk zijn.

Wat we aanraden:

• Bevries merges naar de standaardbranches tijdens de migratie.
• Verifieer eerst één repository van begin tot eind. GitLab CI-pipelines verschillen qua structuur meer van Forgejo Actions dan GitHub Actions, dus het aanpassen kost per repository meer werk.
• Heb je in GitLab CI veel include:-verwijzingen naar andere projecten, breng dan de afhankelijkheidsgraaf in kaart voordat je gaat migreren. Zo voorkom je half gemigreerde pipelines die verwijzen naar templates die ze niet meer kunnen zien.

Geschatte tijd:

• Eén kleine repository met een eenvoudige .gitlab-ci.yml: 30-60 minuten, inclusief het aanpassen van de pipeline.
• Middelgrote repository met gemiddeld complexe CI (DAG, needs:, tags voor eigen runners): 2-4 uur.
• Bulkmigratie van 20-50 repository’s waarvan er veel dezelfde GitLab CI include:-templates delen: 3-5 werkdagen engineering, grotendeels voor het omzetten van de CI.

Vergelijking van functies

Voor beveiliging en authenticatie geldt dezelfde matrix als in de functievergelijking van de GitHub-migratie: fremforge levert voor beide bronnen dezelfde beveiligingsbouwstenen. Nieuwe organisaties krijgen bij fremforge standaard Git-toegang alleen via HTTPS (SSH staat sinds 2026-05-22 standaard uit), met de vooraf geregistreerde OAuth-app voor Git Credential Manager; ontwikkelaars krijgen MFA via de IdP van je organisatie bij elke vernieuwing bij een push. GitLab-specifieke punten:

Stap 1: Repository en geschiedenis migreren

De ingebouwde importer van Forgejo ondersteunt GitLab als bron. Hij kopieert de volledige Git-geschiedenis, issues, merge requests (geïmporteerd als pull requests), opmerkingen, labels, mijlpalen, wiki-inhoud en releases.

Met de ingebouwde importer (via de UI)

Vanuit de beheer-UI van fremforge voor je organisatie:

1. Klik op + → Nieuwe migratie.
2. Kies GitLab als bron.
3. Plak de URL van het GitLab-project (bijvoorbeeld https://gitlab.com/acme/backend).
4. Plak je personal access token van GitLab.
5. Vink de soorten inhoud aan die je wilt importeren: Wiki, Issues, Merge requests, Releases, Labels, Mijlpalen.
6. Kies de doelorganisatie en de naam van de repository op fremforge.
7. Klik op Migreer repository.

Via de API (scriptbaar)

# Build the JSON body via jq so the token is JSON-string-escaped safely
# (a token containing `"` or `\` would otherwise break the body).
jq -nc \
  --arg clone_addr "https://gitlab.com/acme/backend.git" \
  --arg auth_token "$GITLAB_TOKEN" \
  --arg repo_owner "acme" \
  --arg repo_name  "backend" \
  '{clone_addr: $clone_addr, auth_token: $auth_token,
    service: "gitlab", repo_owner: $repo_owner, repo_name: $repo_name,
    wiki: true, issues: true, pull_requests: true,
    releases: true, labels: true, milestones: true,
    lfs: true}' \
| curl -X POST "https://frem.sh/api/v1/repos/migrate" \
    -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
    -H "Content-Type: application/json" \
    -d @-

GitLab-begrippen in fremforge

GitLab en Forgejo gebruiken niet dezelfde woorden. De importer handelt de gangbare gevallen af:

Subgroepen

GitLab ondersteunt willekeurig diep geneste subgroepen. fremforge (Forgejo) gebruikt een plat model van organisatie + repository. Is je GitLab-structuur company / department / team / project, beslis dan vóór de migratie welke van deze opties je kiest:

1. Samenvoegen tot één organisatie: alle projecten worden repository’s <company-slug>/<team>-<project> onder één organisatie. Eenvoudigere rechten, maar je verliest een deel van de hiërarchie.
2. Eén organisatie per groep op het bovenste niveau: <company-department-slug> met platte namen voor repository’s. Je verliest de hiërarchie op afdelingsniveau.
3. Eén organisatie per subgroep: meer organisaties, meer gebruikersbeheer, en elke organisatie wordt apart gefactureerd. Alleen zinvol als de subgroepen echt aparte eisen hebben voor facturatie en toegang.

De importer ondersteunt optie 1 en 2 rechtstreeks. Voor optie 3 moet je meerdere fremforge-organisaties aanmaken en de import N keer uitvoeren.

Stap 2: Secrets en CI/CD-variabelen

GitLab slaat CI/CD-variabelen op op instantie-, groeps-, project- en omgevingsniveau. fremforge Actions ondersteunt secrets en variabelen op organisatie-, omgevings- en repositoryniveau: een hiërarchie van drie niveaus die netjes aansluit op de gangbare gevallen in GitLab.

Belangrijk: van GitLab CI/CD-variabelen die als “masked” zijn gemarkeerd, geeft de API de waarden niet terug. Je moet de waarde dus kennen of ophalen uit je leidende secretsopslag. Dat is dezelfde beperking als bij het migreren van secrets vanaf GitHub.

Variabelen opnieuw invoeren

Beslis per GitLab CI/CD-variabele:

• Is het een langlevende cloudcredential (AWS-toegangssleutel, secret van een Azure-service-principal, AK/SK van T Cloud Public)? Sterk aangeraden: vervang die door OIDC-federatie naar de doelcloud (zie stap 4 hieronder) in plaats van de statische credential mee te migreren.
• Is het een beschermde variabele (een GitLab-begrip: alleen beschikbaar voor beschermde branches/tags)? fremforge heeft daarvoor omgevingssecrets. Stel de doelomgeving in met toegang die afhangt van branchbeveiliging, en zet het secret daar.
• Is het een bestandsvariabele (GitLab slaat de inhoud van een bestand met meerdere regels op als variabele)? fremforge ondersteunt hetzelfde via de gewone secretsopslag. Plak de inhoud met meerdere regels; de runner stelt die tijdens de job beschikbaar als de genoemde omgevingsvariabele.

Stel variabelen en secrets in de beheer-UI van fremforge in op het passende niveau: Instellingen → Secrets (organisatieniveau) of Repository → Instellingen → Geheimen (repositoryniveau).

Stap 3: GitLab CI omzetten naar Forgejo Actions

Dit is de grootste stap in een GitLab-migratie. GitLab CI-pipelines zijn anders opgebouwd dan Forgejo Actions: stages, jobs, extends, include, rules, artifacts en cache komen niet één op één overeen met jobs, steps, needs en uses in GitHub Actions.

Er is geen automatische converter. Automatisch omzetten staat op de roadmap, afhankelijk van de vraag van klanten. Bij de lancering leveren we documentatie en handmatige omzettingspatronen voor de gangbare gevallen.

Omzettingspatronen

Stages → jobs met needs:

GitLab CI deelt pipelines in opeenvolgende stages in. Forgejo Actions deelt ze in parallelle jobs in, met expliciete DAG-afhankelijkheden via needs:.

GitLab CI:

stages: [build, test, deploy]

build:
  stage: build
  script: make build

test:
  stage: test
  script: make test

deploy:
  stage: deploy
  script: make deploy

De tegenhanger in Forgejo Actions (.forgejo/workflows/main.yaml):

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: make build

  test:
    needs: build
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: make test

  deploy:
    needs: test
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: make deploy

extends: → herbruikbare workflows of composite actions

extends: in GitLab CI erft jobconfiguratie. Forgejo Actions heeft twee tegenhangers:

1. Herbruikbare workflows (workflow_call) om hele jobs over workflows heen te erven.
2. Composite actions (runs: using: composite) om reeksen stappen te erven.

Het omzetten gaat met de hand: zoek de bovenliggende job van .extends: in GitLab, kopieer de script: en de setup naar een composite action in .forgejo/actions/<name>/action.yml, en roep die aan met uses: ./.forgejo/actions/<name> vanuit de workflows die hem gebruiken.

include:-templates uit andere projecten

include: project: in GitLab CI haalt CI-configuratie op uit een ander project. Forgejo Actions heeft daar geen directe tegenhanger voor. Herbruikbare workflows (uses: owner/repo/.forgejo/workflows/template.yaml@ref) komen het dichtst in de buurt en werken binnen dezelfde fremforge-organisatie.

Bij migraties met gedeelde templateprojecten (gebruikelijk in organisaties met een CI-platformteam) migreer je eerst de templaterepository en pas je de uses:-verwijzingen in de afnemende repository’s aan als onderdeel van hun eigen migratie.

rules: en only:/except: → if:-expressies

GitLab CI heeft drie overlappende mechanismen om jobs voorwaardelijk uit te voeren. Forgejo Actions gebruikt dezelfde if:-expressiesyntaxis als GitHub Actions.

GitLab:

deploy:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success
    - when: never
  script: make deploy

Forgejo Actions:

deploy:
  if: github.ref == 'refs/heads/main'
  runs-on: fremforge
  steps:
    - uses: actions/checkout@v4
    - run: make deploy

artifacts: → upload-artifact / download-artifact

Artifacts in GitLab CI gaan automatisch door naar volgende stages. Forgejo Actions vereist expliciet actions/upload-artifact in de job die ze maakt en actions/download-artifact in de job die ze gebruikt.

cache: → actions/cache

cache: in GitLab CI komt overeen met actions/cache@v4, met dezelfde semantiek voor cache key en restore key.

services: → sidecars in stappen starten (NIET het services:-blok van de workflow)

services: in GitLab CI (een sidecar met Postgres/Redis enzovoort) vertaalt vandaag NIET naar een services:-blok op fremforge: Forgejo Actions ondersteunt het services:-blok maar beperkt. Declaraties worden zonder fout ingelezen, maar starten nooit iets, dus je test maakt verbinding met localhost:5432 en mislukt. Workflows die afhankelijk zijn van het native services:-blok werken niet.

De ondersteunde route is de sidecar expliciet in een stap te starten. Docker is beschikbaar op de runner (zie Runner-images), dus docker run -d postgres:16 in een setupstap werkt. Veel gebruikelijker is het om de afhankelijkheid direct te draaien met wat het taalecosysteem biedt (Testcontainers voor Java, pytest-docker voor Python, testcontainers-go enzovoort). Voor testopstellingen met meerdere containers is een aanroep van docker compose binnen de VM in een stap het gangbare patroon.

Ondersteuning voor het native services:-blok staat op de roadmap van het platform. Tot die er is, luidt het migratieadvies: herschrijf services:-blokken uit GitLab naar docker run / docker compose / testcontainers binnen een stap, niet naar services:-blokken in Forgejo.

Runner-tags

tags: in GitLab CI kiest specifieke runners. In Forgejo Actions doet runs-on: hetzelfde. De gehoste runners van fremforge hebben het label fremforge (zie Runner-images voor het besturingssysteem en de toolchain van de runner). Eigen runners kunnen zich registreren met eigen labels, en runs-on: spreekt ze aan op de labelnaam.

Leunde je GitLab CI op specifieke privérunners (tags: [gpu], tags: [macos], tags: [on-prem]), dan moet je die eigen runners op fremforge inrichten via de registratie voor eigen runners (BYO). De gehoste runners van fremforge zijn alleen Linux amd64 (zie Runner-images); GPU en macOS zijn niet beschikbaar in het standaardabonnement.

Stap 4: OIDC-federatie voor deployments

Deployen je GitLab CI-pipelines naar cloudinfrastructuur, dan is het de beste praktijk om bij de migratie langlevende credentials te vervangen door OIDC-federatie. fremforge ondersteunt OIDC-tokenfederatie naar T Cloud Public rechtstreeks; voor AWS, Azure en GCP werken de standaardpatronen voor OIDC-federatie.

Inrichten:

1. Ga in de beheer-UI van fremforge naar Instellingen → OIDC Federation → Add target.
2. Voor T Cloud Public: geef de URN van de doel-agency op. De runnerworkflow krijgt een kortlevende JWT met beperkte scope, die de agency in T Cloud Public vertrouwt en inwisselt voor credentials met beperkte scope.
3. Voor AWS/Azure/GCP: stel het OIDC-vertrouwen in de IAM van de doelcloud in met https://frem.sh/_app/runner/oidc als issuer (één globale issuer voor alle tenants; de scheiding per tenant wordt afgedwongen met een voorwaarde op de claim repository_owner, het patroon dat compatibel is met GitHub Actions). Zie build/runners/oidc/ voor het JWKS-endpoint, de volledige set claims en voorbeelden van vertrouwensbeleid per cloud.

Na het inrichten gebruiken workflows de federatie in plaats van statische sleutels. Elke runnerjob krijgt een kortlevend OIDC-ID-token via $ACTIONS_ID_TOKEN_REQUEST_URL; wissel dat aan het begin van de job in voor credentials van T Cloud Public met beperkte scope:

- name: Federate to T Cloud Public
  run: |
    OIDC_TOKEN="$(curl -sSf -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=tcloud-${ORG_SLUG}")"
    CREDS_JSON="$(curl -sSf -X POST \
      "https://iam.eu-de.otc.t-systems.com/v3.0/OS-FEDERATION/token-exchange" \
      -H 'Content-Type: application/json' \
      -d "{\"identity\":{\"id_token\":{\"id\":\"$OIDC_TOKEN\"}},\"scope\":{\"agency\":{\"name\":\"fremforge-deploy\",\"domain\":{\"name\":\"$TCLOUD_DOMAIN\"}}}}")"
    {
      echo "TCLOUD_AK=$(jq -r '.credential.access' <<<"$CREDS_JSON")"
      echo "TCLOUD_SK=$(jq -r '.credential.secret' <<<"$CREDS_JSON")"
      echo "TCLOUD_TOKEN=$(jq -r '.credential.securitytoken' <<<"$CREDS_JSON")"
    } >> "$GITHUB_ENV"

Er komt een wrapper-action die de curl-aanroepen verbergt; de inline vorm hierboven houdt het ruwe OIDC-contract zichtbaar en werkt vandaag al.

Verwijder de bijbehorende secrets met statische credentials zowel uit GitLab als uit fremforge.

Stap 5: SSH-sleutels opnieuw registreren

Zelfde werkwijze als in stap 4 van de GitHub-migratie. Elke ontwikkelaar voegt zijn of haar publieke SSH-sleutel toe aan het eigen fremforge-account.

SSH-certificaatautoriteiten (een functie van GitLab EE) importeer je via <your-org>/_admin/auth-policy: het onderdeel voor de SSH-CA staat onder de schakelaar “SSH-protocol toestaan” (sinds 2026-05-26 onderdeel van het authenticatiebeleid). Het is dezelfde beheer-UI als bij de migratie vanaf GitHub; zie het onderdeel over de SSH-certificaatautoriteit voor de details van het inrichten.

Stap 6: GitLab Pages → externe hosting (geen Pages-tegenhanger in Forgejo)

fremforge levert geen Pages-product. Upstream Forgejo heeft geen Pages-module en wij hebben er geen gebouwd. Migraties van GitLab Pages moeten dus ergens anders terechtkomen; kies de optie die bij jouw situatie past:

1. Markdown-documentatie die in een Pages-site op basis van een repositorywiki stond: zet in de gemigreerde repository de publieke docs-wiki van fremforge aan. De wiki op frem.sh/<org>/<repo>/wiki[/...] levert gerenderde Markdown met anonieme leestoegang, per repository in te schakelen. Let op: dit levert gerenderde Markdown, geen willekeurige statische HTML/JS. Het dekt dus Pages-sites in documentatiestijl, geen Pages-deployments van single-page-apps.

2. Statische HTML/JS-sites (single-page-apps, uitvoer van Hugo / Jekyll / Astro): host ze extern en verwijs met een CNAME vanaf je eigen domein. Redelijke EU-vriendelijke keuzes zijn Bunny Edge Storage + Bunny CDN (dezelfde stack die de marketingsite van fremforge zelf gebruikt), Cloudflare Pages, Netlify of Vercel. Koppel de build opnieuw via runnerworkflows van fremforge die bij een push deployen.

3. Alleen een eigen domein: gebruikte je GitLab Pages eerder voor het TLS-certificaat van een eigen domein (en niet voor de buildstap), richt je DNS dan op je externe host en gebruik de runner-OIDC-federatie van fremforge om rechtstreeks vanuit de workflow te deployen. Een proxy via fremforge is niet nodig.

Heb je een niet-triviale GitLab Pages-pipeline (eigen CI, redirects, deployments per branch), mail dan naar support@frem.sh. We bespreken graag de juiste externe hostingopzet voor jouw situatie voordat je je vastlegt op een migratieplan.

Stap 7: Integraties van derden opnieuw koppelen

De integraties van GitLab (webhookdoelen, Jira-synchronisatie, Slack-meldingen enzovoort) koppel je op dezelfde manier opnieuw als in stap 5 van de GitHub-migratie. De meeste integraties ondersteunen Forgejo standaard.

GitLab-specifieke integraties zonder directe tegenhanger:

• Aggregatie in het GitLab Security Dashboard: de weergave Bevindingen in de beheer-UI van fremforge dient hetzelfde doel voor de meegeleverde supply-chain-stack.
• Value Stream Analytics / DORA-metrics: fremforge levert DORA-metrics (deployfrequentie, doorlooptijd, percentage mislukte wijzigingen, MTTR); zie Organisatiebeheer → DORA. Er is geen externe tool via webhookgebeurtenissen en API-polling nodig.

Stap 8: Verifiëren en uitfaseren

Hetzelfde als in stap 7 van de GitHub-migratie:

1. Klonen, bouwen en controleren dat de tests slagen.
2. Een voorbeeld-PR door de pre-receive-scanner, de dependency-scanner en de verificatie van ondertekende commits halen.
3. Controleren dat webhooks aankomen.
4. Voor elke gebruiker controleren dat inloggen via SSO werkt.
5. De documentatie bijwerken met de nieuwe URL’s.
6. Na 30 dagen probleemloos gebruik de GitLab-projecten archiveren (niet verwijderen).

Veelvoorkomende valkuilen bij GitLab-migraties

Het omzetten van pipelines duurt langer dan je denkt.

Een complexe .gitlab-ci.yml met veel stages, DAG’s, extends:, include: en services: kan per repository een halve dag kosten om nauwkeurig over te zetten. Reken op 2-4 uur per pipeline van gemiddelde complexiteit. De compatibiliteitsmatrix op docs.frem.sh/marketplace-compat richt zich op GitHub Actions; gebruik voor patronen die specifiek zijn voor GitLab CI stap 3 van deze gids en de documentatie van Forgejo Actions.

Goedkeuringsregels voor merge requests

De goedkeuringsregels van GitLab (N goedkeurders vereisen, specifieke groepen goedkeurders, goedkeuring op basis van code-owners) komen overeen met de branchbeveiligingsregels van Forgejo, maar zijn minder fijnmazig. Leunt je GitLab-project op geavanceerde goedkeuringsregels (bijvoorbeeld “andere goedkeurders voor beveiligingsgevoelige paden”), ga dan vóór de migratie na of het model van Forgejo met verplichte reviewers op basis van CODEOWNERS volstaat.

Functies van GitLab Premium/Ultimate

Voor License Compliance van GitLab levert fremforge een directe tegenhanger: licentiescanning voert bij elke PR de licentiedetectie van Trivy uit, deelt elke afhankelijkheid in een SPDX-beleidscategorie in en kan een merge blokkeren bij verboden of beperkte licenties; zichtbaar onder Beveiliging › Bevindingen › Licenties. Voor de rest van de beveiligingssuite van GitLab Ultimate (DAST, fuzz testing, SAST met de ernstregels van Ultimate, Dependency Firewall, Security Dashboards op groepsniveau) levert fremforge geen directe tegenhangers. SAST (OpenGrep), scannen van afhankelijkheden en CVE’s (osv-scanner) en containerscanning (Trivy) dekken wel de meest voorkomende gevallen. Wat we wel en uitdrukkelijk niet dekken, lees je in het bericht over onze AI-aanpak op www.frem.sh en op de productpagina van fremforge.

GitLab-runners met tags voor compliancecontexten

Tags voor GitLab Runner zoals compliance, restricted-network en no-internet worden vaak gebruikt voor runners die het publieke internet niet kunnen bereiken. De gehoste runners van fremforge voldoen daar standaard aan: uses:-instructies worden opgelost via de action-mirrors in de EU op https://frem.sh/<owner>/<repo> (de leidende beschrijving staat op de GitHub-migratiepagina §Stap 3: Actions-workflows aanpassen), en uitgaand verkeer via de proxy is beperkt tot die mirror, gespiegelde pakketregisters en de uitgaande webhooks van de tenant van de klant. Vereist je compliancecontext runners zonder enige internettoegang, gebruik dan eigen runners in je eigen netwerk en laat ze verwijzen naar het registratie-endpoint voor runners van fremforge.

Hulp krijgen

support@frem.sh met onderwerpregel MIGRATION, GITLAB, <your-specific-issue>. Early-adopter-klanten hebben rechtstreeks toegang tot het bouwteam.

Zie ook: Gids voor migratie vanaf GitHub · Gids voor migratie vanaf Azure DevOps · Compatibiliteitsmatrix van de top 20 Marketplace-actions · Checklist voor de migratie.