Migrera till fremforge från Azure DevOps

Den här guiden beskriver migrering från Azure DevOps Services (dev.azure.com) till fremforge. Migrering från motsvarande Azure DevOps Server (on-premises) är likartad, men detaljerna kring autentisering och API-endpoints skiljer sig. Anpassa delarna om token och endpoints nedan efter din egen installation.

Azure DevOps är den av de tre stora migreringskällorna som skiljer sig mest i sin struktur. ADO har separata produkter för Repos, Pipelines, Boards, Test Plans och Artifacts; fremforge levererar repon, CI/CD, artefakter och enkla issues som en integrerad helhet och har inga motsvarigheter till Test Plans eller hela funktionsuppsättningen i Boards. En ADO-migrering är därför delvis ett beslut om omfattning och inte bara en teknisk migrering: en del ADO-funktioner som du kanske är beroende av har ingen destination i fremforge.

Läs guiden för migrering från GitHub och guiden för migrering från GitLab först om du inte redan har gjort det. Några grundläggande steg (SSH-nycklar, tredjepartsintegrationer) är identiska och upprepas inte i sin helhet här.

Innan du börjar

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

• Rollen Project Administrator i det eller de Azure DevOps-projekt du migrerar.
• En personlig åtkomsttoken i ADO med minst scopen Code (Read), Code (Status), Work Items (Read), Build (Read), Release (Read) och Identity (Read).
• Administratörsåtkomst till den fremforge-organisation du migrerar till.
• För migreringen av Pipelines: en inventering av YAML-pipelinefiler, eventuella klassiska pipelines (utan YAML), Service Connections (de blir OIDC-federation), variabelgrupper och de agentpooler du är beroende av.

Det här rekommenderar vi:

• Konvertera alla klassiska pipelines (utan YAML) till YAML-pipelines i ADO innan du migrerar. Att gå från klassiska pipelines till Forgejo Actions är i praktiken en omskrivning från grunden; att konvertera till YAML först ger dig en portabel utgångspunkt och förbättrar dessutom din ADO-uppsättning.
• Ta reda på vilka typer av Work Items i Boards du verkligen använder. fremforge (Forgejo) har issues och milstolpar men har inte Epics, Features, User Stories eller Tasks som separata typer. De slås alla ihop till issues med etiketter. Om din process är beroende av hierarkin av Work Item-typer, planera sammanslagningen före migreringen.
• Ta reda på beroenden till Test Plans. fremforge har ingen direkt motsvarighet; team som är starkt beroende av Test Plans i ADO brukar låta Test Plans i ADO köras vidare som ett separat verktyg eller migrera till ett dedikerat verktyg för testhantering.

Tidsuppskattning:

• Ett enda repo med en enkel pipeline och begränsad användning av Boards: 1–2 timmar.
• Ett repo med måttligt komplexa pipelines och releasepipelines i flera steg: 3–6 timmar.
• Migrering av en hel organisation med många pipelines, variabelgrupper och Service Connections: 1–2 utvecklarveckor, där konverteringen av pipelines och ersättningen av Service Connections tar mest tid.

Steg 1: Migrering av repon och historik

Forgejos inbyggda importör stöder Azure DevOps som källa. Den kopierar Git-historiken och, beroende på din ADO-konfiguration, Work Items (importeras som issues) och pull requests.

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

Från fremforges administrationsgränssnitt:

1. Klicka på + → Ny migrering.
2. Välj Azure DevOps som källa.
3. Klistra in repots URL (t.ex. https://dev.azure.com/acme/project/_git/backend).
4. Klistra in din personliga åtkomsttoken från ADO.
5. Kryssa i de innehållstyper som ska importeras.
6. Ange målorganisation och reponamn.
7. Klicka på Migrate repository.

Med API:t (skriptbart)

# Build the JSON body via jq so the PAT is JSON-string-escaped safely
# (Azure DevOps PATs can contain `/`, `+`, `=` characters which are
# fine in JSON strings but a raw shell-interpolation can still break
# if the PAT happens to contain `"` from a copy-paste error).
jq -nc \
  --arg clone_addr    "https://dev.azure.com/acme/project/_git/backend" \
  --arg auth_username "fremforge" \
  --arg auth_token    "$ADO_TOKEN" \
  --arg repo_owner    "acme" \
  --arg repo_name     "backend" \
  '{clone_addr: $clone_addr, auth_username: $auth_username, auth_token: $auth_token,
    service: "git", repo_owner: $repo_owner, repo_name: $repo_name,
    issues: false, pull_requests: false, lfs: true}' \
| curl -X POST "https://frem.sh/api/v1/repos/migrate" \
    -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
    -H "Content-Type: application/json" \
    -d @-

Observera: ADO är inte ett av de service-värden för migrering som Forgejo känner igen. Uppströms Forgejos enum på protokollnivå är git, github, gitea, gitlab, gogs, onedev, gitbucket, codebase, där git är reservvägen för vanlig Git (en del äldre dokumentation kallar den “plain”, men värdet på protokollnivå är den bokstavliga strängen git). Att uttryckligen sätta "service": "git" (som i anropet ovan) är det kanoniska värdet; ADO-PAT:en i auth_token står för autentiseringen, och klon-URL:en är en vanlig Git-remote över HTTPS som importören för vanlig Git hanterar korrekt. "lfs": true gör att importören hämtar LFS-objekt via källans LFS-endpoint, vilket krävs för ADO-repon med LFS-innehåll. Work Items och PR-metadata importeras sedan separat med ett skriptat flöde mot ADO:s REST API (se nedan); importören för vanlig Git tar bara med refs.

auth_username krävs för ADO. PAT:er i Azure DevOps använder HTTP Basic Auth där lösenordet är PAT:en och användarnamnet måste vara en valfri sträng som inte är tom (Microsofts dokumentation: “When using a PAT, the username can be any non-empty string”). Annars bygger Forgejos importör för vanlig Git URL:er av formen https://{auth_token}@…, som AzDO:s Git-server tolkar som användarnamnet och avvisar med 401. Använd "auth_username": "fremforge" (eller vilken icke-tom sträng som helst; värdet spelar ingen roll för AzDO, bara formen på Basic Auth gör det).

Så motsvarar ADO:s begrepp fremforges

Work Items → issues

Work Items importeras inte via Forgejos inbyggda importör. Migreringsskript:

#!/bin/bash
# Requires: curl, jq, ADO_TOKEN, FREMFORGE_TOKEN
ADO_ORG="acme"
ADO_PROJECT="project"
FREMFORGE_ORG="acme"
FREMFORGE_REPO="backend"

# Query all work items in the project
curl -s -u ":${ADO_TOKEN}" \
  "https://dev.azure.com/${ADO_ORG}/${ADO_PROJECT}/_apis/wit/wiql?api-version=7.1" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject]=@project"}' \
  | jq -r '.workItems[].id' \
  | while read wi_id; do
    # Fetch full work item
    ado_wi=$(curl -s -u ":${ADO_TOKEN}" \
      "https://dev.azure.com/${ADO_ORG}/_apis/wit/workitems/${wi_id}?api-version=7.1")

    title=$(echo "${ado_wi}" | jq -r '.fields."System.Title"')
    body=$(echo "${ado_wi}" | jq -r '.fields."System.Description" // ""')
    wi_type=$(echo "${ado_wi}" | jq -r '.fields."System.WorkItemType"' | tr '[:upper:]' '[:lower:]')
    state=$(echo "${ado_wi}" | jq -r '.fields."System.State"')

    # Create fremforge issue
    curl -s -X POST "https://frem.sh/api/v1/repos/${FREMFORGE_ORG}/${FREMFORGE_REPO}/issues" \
      -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
      -H "Content-Type: application/json" \
      -d "{
        \"title\": \"${title}\",
        \"body\": \"**Migrated from Azure DevOps work item #${wi_id}**\n\n${body}\",
        \"labels\": [\"${wi_type}\"],
        \"closed\": $([[ "${state}" == "Closed" || "${state}" == "Done" || "${state}" == "Resolved" ]] && echo true || echo false)
      }"
  done

Anpassa efter behov. Det här är en utgångspunkt, inte en färdig lösning. Stora migreringar bör lägga till backoff vid hastighetsbegränsning och bevara kommentarer.

Sidindelning i WIQL. Azure DevOps begränsar ett enskilt WIQL-svar till 20 000 Work Items. Skriptet ovan skickar en fråga och itererar över den resultatmängden, vilket räcker i det vanliga fallet. Räkna först, innan du startar det:

COUNT=$(curl -s -u ":${ADO_TOKEN}" \
  "https://dev.azure.com/${ADO_ORG}/${ADO_PROJECT}/_apis/wit/wiql?api-version=7.1" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject]=@project"}' \
  | jq '.workItems | length')
echo "Work items in scope: ${COUNT}"

Om COUNT är över cirka 19 000, dela upp frågan (till exempel per kvartal i [System.CreatedDate] eller per [System.WorkItemType]) och kör skriptet en gång per del, eller kontakta support@frem.sh för mycket stora mängder Work Items. Vägen med en enda fråga trunkerar tyst vid taket: det kommer inget felsvar, bara en kortare resultatmängd, och det är just det felläge du inte vill ha under en migrering.

Steg 2: Secrets och variabler

Lagring av secrets i Azure DevOps:

• Pipelinevariabler (direkt i YAML): skriv om dem i samband med migreringen.
• Variable Groups (på projektnivå, eventuellt kopplade till Azure Key Vault): skapa dem igen som secrets på organisations- eller miljönivå i fremforge.
• Hemliga variabler (markerade som secret, returneras inte via ADO:s API): måste hämtas från det system där dina secrets förvaltas och anges igen.
• Key Vault-referenser: om variabelgruppen är kopplad till Azure Key Vault är migreringsstrategin antingen (a) att behålla Key Vault och låta fremforges runners autentisera mot Azure via OIDC-federation och hämta värdena när jobbet körs, eller (b) att kopiera värdena direkt till secrets i fremforge.

Vi rekommenderar starkt att du ersätter secrets för tjänsteprincipaler i Azure med OIDC-federation mot Azure (se steg 4).

Steg 3: Från Pipelines till Forgejo Actions

YAML i Azure Pipelines och YAML i Forgejo Actions har liknande form men väsentligt olika vokabulär. Konverteringen görs för hand. Automatisk konvertering är uppskjuten till fas 2 och beror på kundernas efterfrågan.

Konverteringsmönster

Stages och jobb

YAML i Azure Pipelines:

trigger: [main]

stages:
  - stage: Build
    jobs:
      - job: BuildApp
        pool:
          vmImage: ubuntu-latest
        steps:
          - script: make build
            displayName: 'Build'

  - stage: Test
    dependsOn: Build
    jobs:
      - job: TestApp
        pool:
          vmImage: ubuntu-latest
        steps:
          - script: make test
            displayName: 'Test'

Motsvarigheten i Forgejo Actions:

name: CI

on:
  push:
    branches: [main]

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

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

Viktiga konverteringar:

• trigger: → on: push: med branch-filter.
• pr: → on: pull_request:.
• schedules: → on: schedule: med cron-uttryck.
• stages / jobs / steps → jobs / steps (en nivå plattare; stages har ingen direkt motsvarighet, och ordningsföljden åstadkoms med needs: mellan jobben).
• pool: vmImage: ubuntu-latest → runs-on: fremforge (se Runner-images för runnerns operativsystem, listan över förinstallerade verktyg och hur du installerar språkverktyg via setup-*-actions).
• script: → run: med samma skalkommando.
• task: <name>@<version> → uses: <action-path>@<version> där action är en motsvarande action från Marketplace. De flesta ADO-tasks har ingen direkt motsvarighet i Forgejo Actions och skrivs om som run:-steg eller små composite actions.

ADO-tasks som ofta behöver konverteras

Villkor

condition: i ADO → if: i Forgejo Actions.

ADO:

- task: Deploy
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))

Forgejo Actions:

- name: Deploy
  if: success() && github.ref == 'refs/heads/main'
  run: make deploy

Mallar och Library

ADO-mallar (extends:, template:) motsvaras av återanvändbara workflows i Forgejo Actions (uses: <repo>/.forgejo/workflows/template.yaml@ref) eller composite actions (uses: ./.forgejo/actions/<name>). Konverteringen görs för hand men är mekanisk.

Releasepipelines i flera steg → driftsättningsjobb styrda av miljöer

Releasepipelines i ADO med godkännandesteg motsvaras av workflows i Forgejo Actions som använder environment: <name> för att starta flödet med obligatoriska granskare och godkännande på miljönivå. Konfigurera skyddsregler för miljöer i fremforges administrationsgränssnitt under Organisationens administration → Miljöer → <name>.

Agentpooler → runner-etiketter

pool: vmImage: windows-latest i ADO → runs-on: windows-latest i Forgejo Actions. De hostade runners som fremforge tillhandahåller är bara Linux amd64. Windows och macOS finns inte i standardabonnemanget.

Om dina pipelines kräver runners med Windows eller macOS finns två vägar:

1. Egna runners: registrera en Windows- eller macOS-runner i din egen infrastruktur med etiketten windows-latest eller macos-latest. Dina pipelines riktar sig mot dem via runs-on:.
2. Behåll de pipelinesen i ADO: för team som migrerar huvuddelen av sin CI men behåller Windows- och Mac-byggen på befintlig infrastruktur. Inte idealiskt, men det stöds som ett övergångsläge.

Steg 4: Service Connections → OIDC-federation

Azure DevOps använder Service Connections för att lagra autentiseringsuppgifter för moln. fremforge ersätter dem med OIDC-federation, som är det rekommenderade sättet för alla molnmål, inte bara Azure.

För Azure

1. Skapa en App Registration i Azure AD och konfigurera en federerad autentiseringsuppgift med:
   • Issuer: https://frem.sh/_app/runner/oidc (en enda global utfärdare för alla tenants; se build/runners/oidc/ för JWKS-endpointen och den fullständiga uppsättningen claims, kompatibel med GitHub Actions)
   • Subject: repo:<fremforge-org>/<repo>:ref:refs/heads/main (eller det avgränsningsmönster du föredrar; subject-claimet innehåller organisationen, så isoleringen per tenant upprätthålls här)
   • Audience: api://AzureADTokenExchange
2. Ge din App Registration de rolltilldelningar som behövs i målprenumerationen eller målprenumerationerna i Azure.
3. I din workflow i Forgejo Actions:

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: fremforge
    steps:
      - uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      - run: az account show

Ingen klient-secret. Ingen långlivad autentiseringsuppgift. Token utfärdas när jobbet körs, är avgränsad till den här workflowen och går ut inom en timme.

För T Cloud Public

Precis som vid GitLab-migreringar (GitLab, steg 4) stöder fremforge inbyggd OIDC-federation till agencies i T Cloud Public. Konfigurera det i fremforges administrationsgränssnitt under Inställningar → OIDC Federation.

För AWS / GCP

De vanliga mönstren för OIDC mot AWS och OIDC mot GCP fungerar på samma sätt som från GitHub Actions. Konfigurera förtroenderelationen med https://frem.sh/_app/runner/oidc som utfärdare (en enda global utfärdare för alla tenants; lås förtroendepolicyns villkor till claimet repository_owner för isolering per tenant, samma mönster som filtret på repository_owner för token.actions.githubusercontent.com i GitHub Actions).

Steg 5: Ny registrering av SSH-nycklar

Se steg 4 i migreringen från GitHub.

Steg 6: Migrering av Boards (delvis)

Som nämnts har fremforge ingen hierarki av Work Item-typer. Alternativ för migreringen:

1. Platta ut: alla Work Items → issues med typetiketter. Frågor och rapporter byggs om kring fremforges sökning.
2. Behåll Boards separat: exportera Work Items från ADO till en platt datafil, arkivera och fortsätt använda ADO Boards för backloggen medan du bara migrerar kod och CI. Det är ett vanligt mellanläge för team som använder Boards på ett avancerat sätt.
3. Ersätt med ett dedikerat projektledningsverktyg: Linear, Jira, Shortcut eller GitHub Projects (om du stannar i GitHubs ekosystem men lämnar ADO). fremforges webhooks och REST API integrerar med alla dessa.

Importskriptet i steg 1 hanterar alternativ 1 med utplattning baserad på etiketter.

Steg 7: Artifact-flöden → fremforges paketregister

Artifact-flöden i ADO motsvaras av fremforges paketregister. Format som stöds i fremforge:

• npm
• Maven
• Docker/OCI-containrar
• NuGet
• PyPI
• RubyGems
• Composer
• Go-moduler
• Generic

Migreringen bygger på push: varje publiceringspipeline publicerar artefakterna på nytt till fremforges register efter migreringen. Historiska versioner av artefakterna i ADO finns kvar där. Avveckla i din egen takt.

Steg 8: Återanslutning av tredjepartsintegrationer

Se steg 5 i migreringen från GitHub. ADO-specifika integrationer (Service Hooks för Teams, ServiceNow, ADO-specifika webhooks) ansluts igen som webhooks i fremforge.

Steg 9: Verifiera och avveckla

Samma som i guiden för GitHub.

Vanliga fallgropar vid ADO-migreringar

Klassiska pipelines kan inte migreras automatiskt.

Om du har klassiska pipelines (utan YAML), konvertera dem till YAML i ADO först. Använd sedan konverteringsmönstren i steg 3. Om du hoppar över mellansteget med YAML måste du återskapa pipelines utifrån den logiska form de har i ADO:s gränssnitt, vilket lätt blir fel.

Service Connections med referenser till Azure Key Vault.

En Service Connection som läser från Azure Key Vault när pipelinen körs kräver en migrering i två steg: (1) sätt upp OIDC-federation så att fremforges runner kan köra az login; (2) workflowen hämtar sedan secreten med az keyvault secret show när jobbet körs, i stället för att den bäddas in i fremforges secrets. Det speglar ADO-mönstret exakt.

Releasepipelines med godkännandesteg.

Releasepipelines i ADO med manuella godkännandesteg före driftsättning i produktion motsvaras av Forgejo Actions med skyddsregler för environment:. I fremforges administrationsgränssnitt kan du konfigurera obligatoriska granskare per miljö. Funktionerna är likvärdiga; bara användarupplevelsen skiljer sig.

Beroende av Test Plans.

Manuell testkörning som följs upp i ADO Test Plans har ingen destination i fremforge. Team som är beroende av det behöver välja ett ersättningsverktyg (Xray för Jira, Zephyr, qTest) eller acceptera den minskade omfattningen.

Få hjälp

support@frem.sh med ämnesraden MIGRATION, AZURE DEVOPS, <your-specific-issue>.

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