Migrera till fremforge från GitLab

Den här guiden beskriver migrering från GitLab till fremforge. Den gäller GitLab.com, självhanterad GitLab (CE eller EE) och GitLab Dedicated. Skillnaderna mellan dem märks mest i hur autentiseringen fungerar och i vilka GitLab-specifika funktioner du kan ha slagit på.

Om du kommer från GitHub, läs guiden för migrering från GitHub först. En del av de självklara stegen är identiska och upprepas inte här.

Om du inte har kört checklistan före migrering mot din nuvarande GitLab-tenant, gör det först. Specifikt för GitLab-migreringar flaggar den förekomsten av korsprojektreferenser med include: i GitLab CI (som måste redas ut för hand) och driftsättningar av GitLab Pages (som behöver ett nytt hem, eftersom fremforge inte har någon Pages-produkt; se steg 6).

Innan du börjar

Det här behöver du på din sida:

• Ett konto med ägarroll i den eller de GitLab-grupper du migrerar.
• En personlig åtkomsttoken i GitLab med scopen api, read_repository, read_user och read_registry.
• Administratörsåtkomst till den fremforge-organisation du migrerar till.
• För CI-migreringen: en inventering av GitLab CI-mallar, include:-referenser och eventuella egna runner-taggar i GitLab som dina pipelines är beroende av.

Det här rekommenderar vi:

• Frys merges till standardbranscherna under migreringen.
• Verifiera ett repo hela vägen först. GitLab CI-pipelines skiljer sig mer i sin struktur från Forgejo Actions än GitHub Actions gör, så anpassningsarbetet per repo är mer omfattande.
• Om du har många korsprojektreferenser med include: i GitLab CI, kartlägg beroendegrafen innan du börjar migrera, så att du inte får halvmigrerade pipelines som refererar till mallar de inte längre ser.

Tidsuppskattning:

• Ett enda litet repo med en enkel .gitlab-ci.yml: 30–60 minuter inklusive anpassning av pipelinen.
• Ett medelstort repo med måttligt komplex CI (DAG, needs:, taggar för egna runners): 2–4 timmar.
• Massmigrering av 20–50 repon där många delar include:-mallar i GitLab CI: 3–5 utvecklardagar, där CI-konverteringen tar mest tid.

Matris över funktionsparitet

För säkerhet och autentisering gäller samma matris som i paritetsmatrisen för migrering från GitHub: fremforge levererar samma säkerhetsfunktioner oavsett källa. fremforge ger nya organisationer Git-åtkomst enbart via HTTPS som standard (SSH är avstängt som standard sedan 2026-05-22) med den förregistrerade OAuth-appen för Git Credential Manager; utvecklare får MFA via organisationens IdP vid varje förnyelse vid push. GitLab-specifika punkter:

Steg 1: Migrering av repon och historik

Forgejos inbyggda importör stöder GitLab som källa. Den kopierar hela Git-historiken, issues, merge requests (importeras som pull requests), kommentarer, etiketter, milstolpar, wikiinnehåll och releaser.

Med den inbyggda importören (via gränssnittet)

Från fremforges administrationsgränssnitt för din organisation:

1. Klicka på + → Ny migrering.
2. Välj GitLab som källa.
3. Klistra in GitLab-projektets URL (t.ex. https://gitlab.com/acme/backend).
4. Klistra in din personliga åtkomsttoken från GitLab.
5. Kryssa i de innehållstyper som ska importeras: Wiki, Issues, Merge requests, Releases, Labels, Milestones.
6. Välj målorganisation och reponamn på fremforge.
7. Klicka på Migrate repository.

Med API:t (skriptbart)

# 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 @-

Så motsvarar GitLabs begrepp fremforges

GitLab och Forgejo använder inte samma vokabulär. Importören hanterar de vanliga fallen:

Undergrupper

GitLab stöder godtyckligt nästlade undergrupper. fremforge (Forgejo) använder en platt modell med organisation och repo. Om din GitLab-struktur är company / department / team / project, bestäm före migreringen om du vill:

1. Slå ihop allt till en enda organisation: alla projekt blir repon med namnet <company-slug>/<team>-<project> i en organisation. Enklare behörigheter, men en del av hierarkin går förlorad.
2. En organisation per grupp på översta nivån: <company-department-slug> med platt namngivning av repona. Hierarkin på avdelningsnivå går förlorad.
3. En organisation per undergrupp: fler organisationer, mer hantering av användare, och var och en faktureras separat. Fungerar bara om undergrupperna verkligen har separata krav på fakturering och åtkomst.

Importören stöder alternativ 1 och 2 direkt. Alternativ 3 kräver att du skapar flera fremforge-organisationer och kör importen N gånger.

Steg 2: Secrets och CI/CD-variabler

GitLab lagrar CI/CD-variabler på instans-, grupp-, projekt- och miljönivå. fremforge Actions stöder secrets och variabler på organisations-, miljö- och reponivå: en hierarki i tre nivåer som täcker GitLabs vanliga fall rakt av.

Viktigt: CI/CD-variabler i GitLab som är markerade som “masked” exporterar inte sina värden via API:t. Du måste antingen känna till värdet eller hämta det från det system där dina secrets egentligen förvaltas. Det är samma begränsning som vid migrering av secrets från GitHub.

Ange variablerna igen

För varje CI/CD-variabel i GitLab, avgör:

• Är det en långlivad molnautentiseringsuppgift (AWS-åtkomstnyckel, secret för en tjänsteprincipal i Azure, AK/SK för T Cloud Public)? Vi rekommenderar starkt att du ersätter den med OIDC-federation mot målmolnet (se steg 4 nedan) i stället för att migrera den statiska autentiseringsuppgiften.
• Är det en skyddad variabel (ett GitLab-begrepp, bara åtkomlig för skyddade branches och taggar)? fremforge har motsvarigheten i form av miljö-secrets. Konfigurera målmiljön så att åtkomsten styrs av branch-skydd, och avgränsa secreten dit.
• Är det en filvariabel (GitLab lagrar flerradigt filinnehåll som en variabel)? fremforge stöder samma sak via den vanliga lagringen av secrets. Klistra in det flerradiga innehållet; runnern gör det tillgängligt som den namngivna miljövariabeln när jobbet körs.

Ange variabler och secrets i fremforges administrationsgränssnitt på motsvarande nivå: Inställningar → Secrets (organisationsnivå) eller Repot → Inställningar → Hemligheter (reponivå).

Steg 3: Från GitLab CI till Forgejo Actions

Det här är det största steget i en GitLab-migrering. GitLab CI-pipelines är uppbyggda annorlunda än Forgejo Actions: stages, jobs, extends, include, rules, artifacts och cache motsvarar inte en-till-en GitHub Actions jobs, steps, needs och uses.

Det finns ingen automatisk konverterare. Automatisk konvertering finns på färdplanen om kunderna efterfrågar det. Vid lansering levererar vi dokumentation och mönster för manuell konvertering som täcker de vanliga fallen.

Konverteringsmönster

Stages → jobb med needs:

GitLab CI delar in pipelines i sekventiella stages. Forgejo Actions delar in dem i parallella jobb med uttryckliga DAG-beroenden 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

Motsvarigheten i 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: → återanvändbara workflows eller composite actions

extends: i GitLab CI ärver jobbkonfiguration. Forgejo Actions har två motsvarigheter:

1. Återanvändbara workflows (workflow_call) för att ärva hela jobb mellan workflows.
2. Composite actions (runs: using: composite) för att ärva sekvenser av steg.

Konverteringen görs för hand: identifiera föräldrajobbet i .extends: i GitLab, kopiera dess script: och förberedelser till en composite action under .forgejo/actions/<name>/action.yml, och anropa den sedan med uses: ./.forgejo/actions/<name> från de workflows som använder den.

Korsprojektmallar med include:

include: project: i GitLab CI hämtar CI-konfiguration från ett annat projekt. Det finns ingen direkt motsvarighet i Forgejo Actions. Återanvändbara workflows (uses: owner/repo/.forgejo/workflows/template.yaml@ref) är det som ligger närmast, och de fungerar inom samma fremforge-organisation.

För migreringar med delade mallprojekt (vanligt i organisationer med CI-plattformsteam): migrera mall-repot först och uppdatera uses:-referenserna i de repon som använder mallarna som en del av deras egen migrering.

rules: och only:/except: → if:-uttryck

GitLab CI har tre överlappande mekanismer för villkorlig körning av jobb. Forgejo Actions använder samma syntax för if:-uttryck som 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

Artefakter i GitLab CI förs automatiskt vidare mellan stages. Forgejo Actions kräver uttryckligen actions/upload-artifact i jobbet som producerar dem och actions/download-artifact i jobbet som använder dem.

cache: → actions/cache

cache: i GitLab CI motsvaras av actions/cache@v4 med samma semantik för cachenyckel och restore-key.

services: → kör sidovagnar i steg (INTE blocket services: i workflowen)

services: i GitLab CI (en sidovagn med Postgres, Redis osv.) blir i dag INTE ett services:-block på fremforge: Forgejo Actions har begränsat stöd för services:-blocket. Deklarationerna tolkas utan fel men startar aldrig något, så ditt test ansluter till localhost:5432 och misslyckas. Workflows som är beroende av det inbyggda services:-blocket fungerar inte.

Den väg som stöds är att starta sidovagnen uttryckligen i ett steg. Docker finns på runnern (se Runner-images), så docker run -d postgres:16 i ett förberedande steg fungerar. Ännu vanligare är att köra beroendet direkt med det språkets ekosystem erbjuder (Testcontainers för Java, pytest-docker för Python, testcontainers-go osv.). För testuppsättningar med flera containrar är ett anrop till docker compose i VM:en inifrån ett steg det idiomatiska mönstret.

Stöd för det inbyggda services:-blocket finns på plattformens färdplan. Tills det kommer är rådet vid migrering: skriv om services:-block från GitLab till docker run / docker compose / testcontainers i steg, inte till services:-block i Forgejo.

Runner-taggar

tags: i GitLab CI väljer specifika runners. runs-on: i Forgejo Actions gör samma sak. De hostade runners som fremforge tillhandahåller använder etiketten fremforge (se Runner-images för runnerns operativsystem och verktyg). Egna runners kan registreras med egna etiketter, och runs-on: riktar sig mot dem via etikettnamnet.

Om din GitLab CI var beroende av specifika privata runners (tags: [gpu], tags: [macos], tags: [on-prem]) måste de egna runnersen sättas upp på fremforge via registreringsflödet för egna runners. fremforges hostade runners är bara Linux amd64 (se Runner-images); GPU och macOS finns inte i standardabonnemanget.

Steg 4: OIDC-federation för driftsättningar

Om dina GitLab CI-pipelines driftsätter till molninfrastruktur är bästa praxis vid migreringen att ersätta långlivade autentiseringsuppgifter med OIDC-federation. fremforge stöder OIDC-tokenfederation till T Cloud Public direkt; för AWS, Azure och GCP fungerar de vanliga mönstren för OIDC-federation.

Så sätter du upp det:

1. I fremforges administrationsgränssnitt: Inställningar → OIDC Federation → Add target.
2. För T Cloud Public: ange målagencyns URN. Runnerns workflow får en kortlivad, avgränsad JWT som T Cloud Public-agencyn litar på och byter mot avgränsade autentiseringsuppgifter.
3. För AWS/Azure/GCP: konfigurera OIDC-förtroendet i målmolnets IAM med https://frem.sh/_app/runner/oidc som utfärdare (en enda global utfärdare för alla tenants; isoleringen per tenant upprätthålls via ett villkor på claimet repository_owner, samma mönster som i GitHub Actions). Se build/runners/oidc/ för JWKS-endpointen, den fullständiga uppsättningen claims och exempel på förtroendepolicyer per moln.

Efter uppsättningen använder workflows federationen i stället för statiska nycklar. Varje runner-jobb får en kortlivad OIDC-ID-token via $ACTIONS_ID_TOKEN_REQUEST_URL; byt den mot avgränsade autentiseringsuppgifter för T Cloud Public när jobbet startar:

- 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"

En wrapper-action som döljer curl-anropen är planerad; den inline-variant som visas ovan håller OIDC-kontraktet synligt och fungerar redan i dag.

Ta bort motsvarande statiska secrets för autentiseringsuppgifter i både GitLab och fremforge.

Steg 5: Ny registrering av SSH-nycklar

Samma process som i steg 4 i migreringen från GitHub. Varje utvecklare lägger till sin publika SSH-nyckel i sitt fremforge-konto.

SSH-certifikatutfärdare (en funktion i GitLab EE) importeras via <your-org>/_admin/auth-policy: avsnittet för SSH-CA ligger under reglaget Tillåt SSH-protokollet (flyttades in i Autentiseringspolicy 2026-05-26). Det är samma administrationsgränssnitt som vid migrering från GitHub; se avsnittet om SSH-certifikatutfärdare för hur du sätter upp det.

Steg 6: GitLab Pages → extern hosting (ingen motsvarighet till Pages i Forgejo)

fremforge har ingen Pages-produkt. Forgejo har ingen Pages-modul uppströms och vi har inte byggt någon. Migreringar av GitLab Pages måste hamna någon annanstans; välj det alternativ som passar ditt fall:

1. Markdown-dokumentation som låg på en Pages-webbplats byggd på en repo-wiki: slå på fremforges wiki för publik dokumentation i det migrerade repot. Wikin på frem.sh/<org>/<repo>/wiki[/...] levererar renderad Markdown med anonym läsning påslagen per repo. Observera: den levererar renderad Markdown, inte godtycklig statisk HTML/JS. Den täcker alltså Pages-webbplatser i dokumentationsstil, inte Pages-driftsättningar av single-page-appar.

2. Statiska HTML/JS-webbplatser (single-page-appar, utdata från Hugo / Jekyll / Astro): hosta dem externt och peka med CNAME från din egen domän. Rimliga EU-vänliga val är Bunny Edge Storage + Bunny CDN (samma stack som fremforges egen marknadsföringswebbplats använder), Cloudflare Pages, Netlify eller Vercel. Anslut bygget igen via fremforges runner-workflows som driftsätter vid push.

3. Bara egen domän: om du tidigare använde GitLab Pages för TLS-certifikatet till en egen domän (snarare än för byggsteget), peka din DNS mot den externa värden och återanvänd fremforges OIDC-federation för runners för att driftsätta direkt från workflowen. Ingen proxy via fremforge behövs.

Om du har en icke-trivial GitLab Pages-pipeline (egen CI, omdirigeringar, driftsättningar per branch), mejla support@frem.sh. Vi kan diskutera vilken extern hosting som passar ditt fall innan du låser fast en migreringsplan.

Steg 7: Återanslutning av tredjepartsintegrationer

GitLabs integrationer (webhook-mål, Jira-synkronisering, Slack-aviseringar osv.) ansluts på samma sätt som i steg 5 i migreringen från GitHub. De flesta integrationer har stöd för Forgejo direkt.

GitLab-specifika integrationer utan direkt motsvarighet:

• Sammanställningen i GitLab Security Dashboard: vyn Fynd i fremforges administrationsgränssnitt fyller samma funktion för den medföljande stacken för leveranskedjesäkerhet.
• Value Stream Analytics / DORA-mått: fremforge levererar DORA-mått (driftsättningsfrekvens, ledtid, andel misslyckade ändringar, MTTR); se Organisationens administration → DORA. Inget externt verktyg behövs, måtten bygger på webhook-händelser och API-anrop.

Steg 8: Verifiera och avveckla

Samma som i steg 7 i migreringen från GitHub:

1. Klona, bygg och verifiera att testerna går igenom.
2. Kör en exempel-PR genom pre-receive-skannern, beroendeskannern och verifieringen av signerade commits.
3. Verifiera att webhooks levereras.
4. Verifiera SSO-inloggning för varje användare.
5. Uppdatera dokumentationen med de nya URL:erna.
6. Efter 30 dagars problemfri drift: arkivera GitLab-projekten (ta inte bort dem).

Vanliga fallgropar vid GitLab-migreringar

Konverteringen av pipelines tar längre tid än du tror.

En komplex .gitlab-ci.yml med många stages, DAG:ar, extends:, include: och services: kan ta en halv dag per repo att överföra korrekt. Räkna med 2–4 timmar per pipeline av medelhög komplexitet. Kompatibilitetsmatrisen på docs.frem.sh/marketplace-compat fokuserar på GitHub Actions; för mönster som är specifika för GitLab CI, använd steg 3 i den här guiden och dokumentationen för Forgejo Actions.

Godkännanderegler för merge requests

GitLabs godkännanderegler (kräv N godkännare, specifika grupper av godkännare, godkännande baserat på kodägare) motsvaras av Forgejos regler för branch-skydd, men med mindre finkornighet. Om ditt GitLab-projekt är beroende av avancerade godkännanderegler (t.ex. “olika godkännare för säkerhetskänsliga sökvägar”), utvärdera före migreringen om Forgejos modell med obligatoriska granskare baserad på CODEOWNERS räcker.

Funktioner i GitLab Premium/Ultimate

fremforge har en direkt motsvarighet till GitLabs License Compliance: licensskanning kör Trivys licensdetektering på varje PR, klassificerar varje beroende efter SPDX-policykategori och kan blockera merge vid förbjudna eller begränsade licenser. Resultatet visas under Säkerhet › Fynd › Licenser. För resten av säkerhetssviten i GitLab Ultimate (DAST, fuzz-testning, SAST med Ultimates allvarlighetsregler, Dependency Firewall, Security Dashboards på gruppnivå) har fremforge inga direkta motsvarigheter, men SAST (OpenGrep), beroende- och CVE-skanning (osv-scanner) och containerskanning (Trivy) täcker de vanligaste fallen. Se inlägget om vår AI-hållning på www.frem.sh och fremforges produktsida för vad vi täcker och vad vi uttryckligen inte täcker.

GitLab-runners taggade för regelefterlevnad

Runner-taggar i GitLab som compliance, restricted-network och no-internet används ofta för runners som inte når det publika internet. fremforges hostade runners uppfyller det kravet av design: uses:-direktiv löses upp via speglarna för actions i EU på https://frem.sh/<owner>/<repo> (den kanoniska beskrivningen finns i migreringssidan för GitHub, §Steg 3: Anpassning av Actions-workflows), och utgående trafik via proxyn är begränsad till den spegeln, speglade paketregister och kundtenantens utgående webhooks. Om din regelefterlevnad kräver runners helt utan internet, använd egna runners i ditt eget nätverk och peka dem mot fremforges endpoint för registrering av runners.

Få hjälp

support@frem.sh med ämnesraden MIGRATION, GITLAB, <your-specific-issue>. Kunder som är tidiga användare har direkt tillgång till utvecklingsteamet.

Se även: Guide för migrering från GitHub · Guide för migrering från Azure DevOps · Kompatibilitetsmatris för de 20 mest använda Marketplace-actions · Checklista före migrering.