Migrer til fremforge fra Azure DevOps

Denne veiledningen dekker migrering fra Azure DevOps Services (dev.azure.com) til fremforge. Migrering fra Azure DevOps Server (lokalt installert) er lik, men detaljene for autentisering og API-endepunkter er annerledes. Tilpass delene om token og endepunkter nedenfor til ditt eget oppsett.

Azure DevOps er den av de tre store migreringskildene som er mest annerledes i oppbygningen. ADO har egne produkter for Repos, Pipelines, Boards, Test Plans og Artifacts; fremforge leverer Repos, CI/CD, Artifacts og grunnleggende issues som én samlet flate, og har ikke noe tilsvarende for Test Plans eller hele funksjonssettet i Boards. En ADO-migrering er derfor delvis en avgjørelse om omfang og ikke bare en teknisk migrering: noen ADO-funksjoner du kanskje er avhengig av, har ikke noe sted å flytte til i fremforge.

Les migreringsveiledningen for GitHub og migreringsveiledningen for GitLab først hvis du ikke har gjort det. Noen grunnleggende steg (SSH-nøkler, tredjepartsintegrasjoner) er identiske, og vi gjentar dem ikke i sin helhet her.

Før du begynner

Dette trenger du på din side:

• Rollen Project Administrator i Azure DevOps-prosjektet eller -prosjektene du migrerer.
• Et personlig tilgangstoken i ADO med minst scopene Code (Read), Code (Status), Work Items (Read), Build (Read), Release (Read) og Identity (Read).
• Administratortilgang til fremforge-organisasjonen du migrerer til.
• For migrering av Pipelines: en oversikt over YAML-pipelinefiler, eventuelle klassiske pipelines (ikke YAML), service connections (disse blir OIDC-føderasjon), variabelgrupper og agentpooler du er avhengig av.

Dette anbefaler vi:

• Konverter alle klassiske pipelines (ikke YAML) til YAML-pipelines i ADO før migreringen. Migrering fra klassiske pipelines til Forgejo Actions er i praksis en full omskriving; ved å konvertere til YAML først får du et flyttbart utgangspunkt, og ADO-oppsettet ditt blir også bedre.
• Finn ut hvilke work item-typer i Boards du faktisk bruker. fremforge (Forgejo) har issues og milepæler, men har ikke Epics, Features, User Stories eller Tasks som egne typer. Alle blir slått sammen til issues med etiketter. Hvis prosessen deres avhenger av typehierarkiet for work items, bør du planlegge sammenslåingen før migreringen.
• Finn avhengigheter til Test Plans. fremforge har ikke noe direkte tilsvarende; team som er sterkt avhengige av ADO Test Plans, beholder som regel ADO Test Plans som et eget verktøy eller går over til et dedikert verktøy for testadministrasjon.

Tidsanslag:

• Ett repository med enkel pipeline og lite bruk av Boards: 1–2 timer.
• Repository med middels kompleks pipeline og utgivelsespipelines i flere steg: 3–6 timer.
• Migrering av hele organisasjonen med mange pipelines, variabelgrupper og service connections: 1–2 ingeniøruker, der mesteparten går med til konvertering av pipelines og utskifting av service connections.

Steg 1: Migrering av repository og historikk

Forgejos innebygde importverktøy støtter Azure DevOps som kilde. Det kopierer Git-historikk og, avhengig av ADO-oppsettet ditt, work items (importert som issues) og pull requests.

Med det innebygde importverktøyet (via webgrensesnittet)

Fra administrasjonsgrensesnittet i fremforge:

1. Klikk + → Ny migrasjon.
2. Velg Azure DevOps som kilde.
3. Lim inn URL-en til repositoryet (f.eks. https://dev.azure.com/acme/project/_git/backend).
4. Lim inn det personlige tilgangstokenet ditt for ADO.
5. Kryss av for innholdstypene som skal importeres.
6. Velg målorganisasjon og navn på repositoryet.
7. Klikk Migrer repository.

Med API-et (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 @-

Merk: ADO er ikke en av service-verdiene for migrering som Forgejo kjenner igjen. Upstream-Forgejos enum på protokollnivå er git, github, gitea, gitlab, gogs, onedev, gitbucket, codebase, der git er reserveløsningen for ren Git (noe eldre dokumentasjon kaller den «plain», men verdien som sendes, er den bokstavelige strengen git). Å sette "service": "git" eksplisitt (som i innholdet over) er den kanoniske verdien; ADO-tokenet i auth_token står for autentiseringen, og klone-URL-en er en vanlig HTTPS-git-remote som importverktøyet for ren Git håndterer riktig. "lfs": true får importverktøyet til å hente LFS-objekter gjennom LFS-endepunktet hos kilden, noe som kreves for ADO-repositoryer med LFS-innhold. Work items og PR-metadata importeres deretter separat med en skriptet arbeidsflyt via ADOs REST-API (se nedenfor); importverktøyet for ren Git henter bare refs.

auth_username er påkrevd for ADO. Personlige tilgangstokener i Azure DevOps bruker HTTP Basic Auth, der passordet er tokenet og brukernavnet må være en hvilken som helst streng som ikke er tom (Microsoft-dokumentasjonen: «When using a PAT, the username can be any non-empty string»). Ellers ville importverktøyet for ren Git i Forgejo bygge URL-er av typen https://{auth_token}@…, som Git-serveren i AzDO tolker som brukernavnet og avviser med 401. Bruk "auth_username": "fremforge" (eller en hvilken som helst streng som ikke er tom; verdien spiller ingen rolle for AzDO, bare formen på basic auth gjør det).

Slik tilsvarer ADO-begrepene fremforge

Work items → issues

Work items importeres ikke med Forgejos innebygde importverktøy. 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

Tilpass ved behov. Dette er et utgangspunkt, ikke en ferdig løsning. Store migreringer bør legge til venting ved frekvensgrenser og bevaring av kommentarer.

Sideinndeling i WIQL. Azure DevOps begrenser ett WIQL-svar til 20 000 work items. Skriptet over sender én spørring og går gjennom det resultatsettet, noe som holder i de vanlige tilfellene. Før du starter det, teller du først:

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

Hvis COUNT er over ca. 19 000, deler du opp spørringen (for eksempel etter kvartal i [System.CreatedDate] eller etter [System.WorkItemType]) og kjører skriptet én gang per del, eller kontakter support@frem.sh for svært store mengder work items. Veien med én spørring avkorter stille ved grensen. Det kommer ingen feilmelding, bare et for kort resultatsett, og det er nettopp den feilmodusen du ikke vil ha under en migrering.

Steg 2: Secrets og variabler

Lagre for secrets i Azure DevOps:

• Pipelinevariabler (direkte i YAML): skrives om ved migreringen.
• Variable Groups (på prosjektnivå, eventuelt koblet til Azure Key Vault): opprettes på nytt som organisasjons- eller miljø-secrets i fremforge.
• Hemmelige variabler (merket som secret, returneres ikke av ADO-API-et): må hentes fra kilden der du oppbevarer secrets, og legges inn på nytt.
• Key Vault-referanser: hvis variabelgruppen er koblet til Azure Key Vault, er strategien enten (a) å beholde Key Vault og la fremforges runnere autentisere seg mot Azure via OIDC-føderasjon og hente verdiene når jobben kjører, eller (b) å kopiere verdiene direkte inn i secrets i fremforge.

Sterk anbefaling: erstatt secrets for service principals i Azure med OIDC-føderasjon til Azure (se steg 4).

Steg 3: Konvertering fra Pipelines til Forgejo Actions

YAML i Azure Pipelines og YAML i Forgejo Actions har lignende form, men vesentlig ulikt vokabular. Konverteringen gjøres manuelt. Automatisk konvertering er utsatt til fase 2, avhengig av etterspørsel fra kunder.

Konverteringsmønstre

Stages og jobber

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'

Tilsvarende 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

De viktigste konverteringene:

• trigger: → on: push: med branchfiltre.
• pr: → on: pull_request:.
• schedules: → on: schedule: med cron-uttrykk.
• stages / jobs / steps → jobs / steps (ett nivå flatere; stages har ingen direkte motsvarighet, og rekkefølgen oppnås med needs: mellom jobbene).
• pool: vmImage: ubuntu-latest → runs-on: fremforge (se Runner-imager for runnerens operativsystem, listen over forhåndsinstallerte verktøy og hvordan du installerer språkverktøy med setup-*-actions).
• script: → run: med samme skallkommando.
• task: <name>@<version> → uses: <action-path>@<version>, der actionen er en tilsvarende Marketplace-action. De fleste ADO-tasks har ingen direkte motsvarighet i Forgejo Actions og skrives om som run:-steg eller små sammensatte actions.

ADO-tasks som ofte må konverteres

Betingelser

ADO condition: → Forgejo Actions if:.

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

Maler og Library

ADO-maler (extends:, template:) tilsvarer gjenbrukbare workflower i Forgejo Actions (uses: <repo>/.forgejo/workflows/template.yaml@ref) eller sammensatte actions (uses: ./.forgejo/actions/<name>). Konverteringen er manuell, men mekanisk.

Utgivelsespipelines i flere steg → utrullingsjobber med sperre per miljø

Utgivelsespipelines i ADO med godkjenningssperrer tilsvarer Forgejo Actions-workflower som bruker environment: <name> for å utløse flyten med påkrevde godkjennere på miljønivå. Sett opp beskyttelsesregler for miljøet i administrasjonsgrensesnittet i fremforge under Organisasjonsadministrasjon → Miljøer → <name>.

Agentpooler → runner-etiketter

ADO pool: vmImage: windows-latest → Forgejo Actions runs-on: windows-latest. De hostede runnerne fremforge leverer, er bare Linux amd64. Windows og macOS er ikke tilgjengelig i standardplanen.

Hvis pipelinene dine krever Windows- eller macOS-runnere, finnes det to veier:

1. Egne runnere (BYO): registrer en Windows- eller macOS-runner på din egen infrastruktur med etiketten windows-latest eller macos-latest. Pipelinene dine retter seg mot dem via runs-on:.
2. Behold de pipelinene i ADO: for team som flytter mesteparten av CI-en, men beholder Windows-/Mac-bygg på eksisterende infrastruktur. Ikke ideelt, men støttet som en overgangsløsning.

Steg 4: Service connections → OIDC-føderasjon

Azure DevOps bruker service connections til å lagre legitimasjon for skyen. fremforge erstatter disse med OIDC-føderasjon, som er den foretrukne tilnærmingen for alle skymål, ikke bare Azure.

For Azure

1. Opprett en App Registration i Azure AD og sett opp en føderert legitimasjon med:
   • Issuer: https://frem.sh/_app/runner/oidc (én global utsteder for alle kunder; se build/runners/oidc/ for JWKS-endepunktet og hele settet med claims som er kompatibelt med GitHub Actions)
   • Subject: repo:<fremforge-org>/<repo>:ref:refs/heads/main (eller det avgrensningsmønsteret du foretrekker; subject-claimen inneholder organisasjonen, så isolasjonen mellom kunder håndheves her)
   • Audience: api://AzureADTokenExchange
2. Gi App Registration de rolletildelingene som trengs på Azure-abonnementet eller -abonnementene det gjelder.
3. I Forgejo Actions-workflowen din:

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 client secret. Ingen langlivet legitimasjon. Tokenet utstedes når jobben kjører, er avgrenset til denne workflowen og utløper innen en time.

For T Cloud Public

Som ved migrering fra GitLab (GitLab, steg 4) støtter fremforge innebygd OIDC-føderasjon til agencies i T Cloud Public. Sett det opp i administrasjonsgrensesnittet i fremforge under Innstillinger → OIDC Federation.

For AWS / GCP

De vanlige mønstrene for OIDC til AWS og OIDC til GCP virker på samme måte som fra GitHub Actions. Sett opp tillitsforholdet med https://frem.sh/_app/runner/oidc som utsteder (én global utsteder for alle kunder; lås betingelsen i tillitspolicyen til claimen repository_owner for isolasjon mellom kunder, samme mønster som filteret på repository_owner i GitHub Actions mot token.actions.githubusercontent.com).

Steg 5: Ny registrering av SSH-nøkler

Se GitHub-migrering, steg 4.

Steg 6: Migrering av Boards (delvis)

Som nevnt har fremforge ikke noe typehierarki for work items. Alternativer for migrering:

1. Flat ut: alle work items → issues med typeetiketter. Spørringer og rapporter bygges opp på nytt rundt søket i fremforge.
2. Behold Boards for seg: eksporter work items fra ADO til en flat datafil, arkiver, og fortsett å bruke ADO Boards til backlog-styring mens bare kode og CI migreres. Dette er en vanlig overgangsløsning for team som bruker Boards avansert.
3. Erstatt med et dedikert prosjektstyringsverktøy: Linear, Jira, Shortcut, GitHub Projects (hvis du blir i GitHub-økosystemet, men forlater ADO). Webhookene og REST-API-et i fremforge kan integreres med alle disse.

Importskriptet i steg 1 håndterer alternativ 1 med utflating basert på etiketter.

Steg 7: Artifact-feeder → fremforges pakkeregister

Artifact-feeder i ADO tilsvarer fremforges pakkeregister. Formater som støttes i fremforge:

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

Migreringen er basert på publisering: hver pipeline som publiserer, publiserer artefaktene på nytt til fremforge-registeret etter migreringen. Tidligere artefaktversjoner i ADO er fortsatt tilgjengelige der. Fas dem ut i ditt eget tempo.

Steg 8: Ny tilkobling av tredjepartsintegrasjoner

Se GitHub-migrering, steg 5. ADO-spesifikke integrasjoner (Service Hooks for Teams, ServiceNow, ADO-spesifikke webhooker) kobles til på nytt som webhooker i fremforge.

Steg 9: Kontroller og fas ut

Som i GitHub-veiledningen.

Vanlige fallgruver ved ADO-migreringer

Klassiske pipelines kan ikke migreres automatisk.

Hvis du har klassiske pipelines (ikke YAML), konverterer du dem til YAML i ADO først. Bruk deretter konverteringsmønstrene i steg 3. Hopper du over mellomsteget med YAML, må pipelinene gjenskapes ut fra den logiske formen i ADO-grensesnittet, noe som lett gir feil.

Service connections med referanser til Azure Key Vault.

En service connection som leser fra Azure Key Vault når pipelinen kjører, må migreres i to steg: (1) sett opp OIDC-føderasjon slik at fremforge-runneren kan kjøre az login; (2) workflowen henter deretter secreten med az keyvault secret show når jobben kjører, i stedet for å legge den inn i secrets i fremforge. Dette speiler ADO-mønsteret nøyaktig.

Utgivelsespipelines med godkjenningssperrer.

Utgivelsespipelines i ADO med manuelle godkjenningssperrer før utrulling til produksjon tilsvarer Forgejo Actions med beskyttelsesregler for environment:. Administrasjonsgrensesnittet i fremforge lar deg sette opp påkrevde godkjennere per miljø. Funksjonene er likeverdige; bare brukeropplevelsen er annerledes.

Avhengighet til Test Plans.

Manuell testkjøring som følges opp i ADO Test Plans, har ikke noe sted å flytte til i fremforge. Team som er avhengige av dette, må velge et erstatningsverktøy (Xray i Jira, Zephyr, qTest) eller godta det reduserte omfanget.

Få hjelp

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

Se også: Migreringsveiledning for GitHub · Migreringsveiledning for GitLab · Kompatibilitetsmatrise for de 20 mest brukte Marketplace-actions · Sjekkliste før migrering.