Skip to main content

Azure DevOps to NCV GitLab Migration Guide

1. Scope

This guide migrates engineering delivery from Azure DevOps Services to:
It covers:
  • Azure Repos Git repositories;
  • Git LFS and submodules;
  • branch policies;
  • Azure Pipelines YAML and Classic pipelines;
  • variable groups and secure files;
  • service connections;
  • Azure Artifacts feeds;
  • build artifacts and release pipelines;
  • deployment environments;
  • repository webhooks/integrations;
  • validation, cutover, and rollback.
Jira Cloud remains NCV’s work-management source of truth. This guide does not migrate Azure Boards unless a separate approved workstream is created.

2. Key migration truths

  1. A Git mirror moves Git commits, branches, tags, and refs.
  2. Git LFS objects require an explicit fetch/push step.
  3. Azure pull-request discussions, approvals, pipeline history, logs, and work items do not become GitLab merge requests/pipelines through a Git mirror.
  4. Pipeline YAML must be translated from Azure syntax to GitLab CI syntax.
  5. Azure Classic pipelines must be documented and rewritten; there is no reliable one-click conversion.
  6. Secrets must be recreated, not copied into YAML or migration logs.
  7. Azure remains read-only for historical evidence after cutover until the retention decision is approved.
  8. The final mirror must occur during a write freeze, and refs must be verified before GitLab becomes canonical.

3. Migration strategy

Use controlled waves: Do not migrate every repository in one weekend. A pilot must pass before Wave 2.

4. Roles

For every repository assign:
  • migration owner;
  • Azure repository owner;
  • GitLab project Maintainer;
  • pipeline owner;
  • deployment owner;
  • secret owner;
  • QA/UAT owner;
  • business cutover approver.
One named migration coordinator controls freeze times and canonical-source changes.

5. Inventory

Start with templates/azure-migration-inventory.csv. For each Azure repository record:
  • organization and project;
  • repository name and clone URL;
  • intended GitLab namespace/project;
  • default branch;
  • branch/tag count;
  • size;
  • Git LFS use and estimated size;
  • submodules;
  • branch policies and required reviewers;
  • YAML pipelines;
  • Classic build/release pipelines;
  • triggers/schedules/path filters;
  • agent pools/demands;
  • variable groups;
  • secret variables;
  • secure files;
  • service connections;
  • environments/approvals/checks;
  • Azure Artifacts feeds and package types;
  • container registries;
  • deployment targets and rollback;
  • webhooks and status checks;
  • external documentation links;
  • risk class and migration wave.
Useful Azure CLI commands, after approved login/configuration:
Azure CLI coverage varies by resource. Export human-readable screenshots/JSON for settings that cannot be reliably listed through CLI. Do not export secret values into the inventory CSV.

6. Destination preparation

Before migrating a repository:
  1. create the GitLab group/project;
  2. leave the repository empty;
  3. set visibility to Private;
  4. set the intended default branch name;
  5. assign Maintainer/Developer access;
  6. configure branch/tag protection;
  7. disable automatic pipeline execution if the imported repository contains untrusted or not-yet-converted .gitlab-ci.yml content;
  8. create required CI variables without values exposed to developers who do not need them;
  9. create the Jira link/integration;
  10. record the GitLab project ID and clone URL.
For a source product project:
For customer-download releases:
Do not combine proprietary source with a publicly downloadable release project.

7. Authentication for migration

Azure source

Use a short-lived credential with repository read access. Prefer the current organization-approved Entra/Azure DevOps authentication method. If a PAT is used:
  • scope it to Code Read;
  • give it the shortest practical expiry;
  • store it in the credential manager/environment, not the command line;
  • revoke it after migration.

GitLab destination

Use:
  • SSH key for a named migration operator; or
  • short-lived project/personal token with only required repository write scope.
Avoid embedding credentials in URLs. If unavoidable for a tool, run in a protected temporary environment and sanitize/remove the bare repository afterward.

8. Pilot repository migration

8.1 Pre-migration test

On Azure:
  • confirm repository builds;
  • confirm default branch and latest SHA;
  • resolve failed branch policies/pipelines;
  • identify LFS and submodules;
  • list active pull requests;
  • choose whether active work finishes in Azure or is recreated in GitLab;
  • freeze changes for the test snapshot if exact comparison is required.
Capture:

8.2 Mirror the repository

Use the supplied script:
The script:
  • performs git clone --mirror;
  • fetches all LFS objects when Git LFS is available;
  • pushes all refs with --mirror;
  • pushes all LFS objects;
  • writes non-secret evidence;
  • redacts the source remote before handoff.
git push --mirror can delete refs in the destination that do not exist in the source. It is appropriate only while Azure is canonical and the GitLab target is empty/frozen.

8.3 Verify refs

This compares:
  • branches;
  • tags;
  • default branch;
  • default HEAD SHA.
Also make a clean clone:
Build and test from this clean GitLab clone. A mirror comparison alone does not prove the project can be consumed.

8.4 Default branch and protection

Confirm in GitLab:
  • correct default branch;
  • main protected;
  • direct push policy;
  • allowed merge role;
  • force push disabled;
  • protected semantic-version release tag pattern;
  • delete source branch policy;
  • pipeline required before merge where configured.

9. Active pull requests

A Git mirror does not import Azure pull-request metadata as GitLab merge requests. Choose one approach per PR:

Approach A: finish in Azure before cutover

Preferred for PRs close to completion. Merge, then include in final mirror.

Approach B: recreate in GitLab

For long-running work:
  1. ensure source branch is mirrored;
  2. create a GitLab merge request;
  3. link the Azure PR in the description;
  4. copy only essential context/decisions—not secrets or excessive history;
  5. ask reviewers to re-approve in GitLab;
  6. mark Azure PR abandoned/read-only after cutover.

Approach C: defer repository cutover

Use when numerous high-risk PRs make a clean freeze impractical. Do not falsely state that Azure PR approvals/comments were migrated by Git.

10. Pipeline conversion model

10.1 Concept mapping

10.2 YAML conversion procedure

For each pipeline:
  1. Write the current pipeline’s behaviour in plain language.
  2. List triggers, inputs, secrets, agent OS, tasks, artifacts, environments and approvals.
  3. Separate validation, build, package, deploy and release responsibilities.
  4. Map to shared GitLab templates.
  5. Convert one stage at a time.
  6. Run Azure and GitLab pipelines against the same commit.
  7. Compare test results, produced files, checksums where reproducible, deployment effects and timing.
  8. Resolve differences before cutover.
  9. Disable Azure trigger only after GitLab acceptance.
Do not translate task-for-task mechanically if the Azure pipeline is tangled. Preserve required behaviour, then simplify around the NCV pipeline standard.

11. Trigger conversion

Azure example:
GitLab equivalent pattern:
Path filters convert to rules:changes:
Validate whether a monorepo job must run on dependency/config changes outside its immediate directory.

12. Agent pool conversion

Azure:
GitLab:
NCV runner tags:
Do not make platform-native jobs run on the wrong OS. A Linux runner cannot produce a normal signed Flutter Windows release or an Apple App Store build.

13. Variables and variable groups

13.1 Classification

For every Azure variable, classify as:
  • non-secret project configuration;
  • secret project value;
  • shared group secret;
  • environment-specific secret;
  • generated/temporary value;
  • obsolete.
Do not migrate unused variables “just in case.”

13.2 GitLab destination

Use GitLab project or group CI/CD variables: Secret migration process:
  1. secret owner retrieves or recreates it through approved vault/provider;
  2. administrator enters it directly into GitLab UI/secret manager;
  3. migration engineer does not receive a plaintext spreadsheet;
  4. run an authentication test;
  5. rotate the old Azure credential after cutover;
  6. delete temporary secure files.

14. Secure files

Inventory every Azure secure file, including:
  • Android keystores;
  • provisioning profiles;
  • Apple certificates/keys;
  • Windows signing certificates;
  • SSH private keys;
  • service-account JSON;
  • license files.
For GitLab:
  • use file-type CI variables for smaller protected files where appropriate;
  • use a dedicated secret manager for high-value signing material;
  • install signing identities on dedicated Windows/macOS runners with restricted service accounts;
  • do not expose production signing files to merge-request pipelines;
  • ensure artifacts never include the secret file.
Record fingerprint/expiry, not secret contents.

15. Service connections

For every Azure service connection record:
  • provider/target;
  • identity type;
  • permissions;
  • environments using it;
  • credential expiry;
  • owner;
  • replacement authentication method.
Preferred replacement order:
  1. workload identity/OIDC with short-lived credentials, when the target supports it;
  2. dedicated service principal/account with least privilege and rotation;
  3. protected deploy token/key;
  4. long-lived static credential only when unavoidable.
Do not migrate a broadly privileged Azure service connection into one group-level GitLab variable shared with all projects.

16. Azure Pipelines task examples

Cache

Azure:
GitLab:

Publish test results

Azure:
GitLab:

Publish pipeline artifact

Azure:
GitLab:
Release binaries must subsequently be published to Generic Packages; job artifacts are not the long-term customer distribution model.

17. Classic build/release pipelines

For each Classic pipeline:
  1. export screenshots and task definitions;
  2. document inputs, variable groups, agent pool, tasks, artifacts, approvals, gates, schedules and retention;
  3. identify scripts hidden in inline task fields;
  4. move reusable script logic into version-controlled repository files;
  5. build a GitLab pipeline from tested scripts/templates;
  6. run in a non-production environment;
  7. perform a controlled production simulation/approval;
  8. preserve Azure pipeline read-only for history.
A Classic UI pipeline often contains undocumented operational knowledge. Migration is incomplete until that knowledge is in code and runbooks.

18. Azure Artifacts migration

18.1 Supported GitLab package types

GitLab supports registries such as Maven, npm, NuGet, PyPI, Generic Packages and Container Registry. Map packages to the native registry where supported. Examples: Do not tell Linux systems to use a Generic Package endpoint as an apt or yum repository.

18.2 Package migration rules

  • Preserve package name and version when legal/compatible.
  • Verify checksums before and after upload.
  • Keep packages immutable.
  • Migrate only versions still needed for builds/support/audit unless retention requires all.
  • Update dependency configuration only after the destination package exists.
  • Test resolution from a clean build environment.
  • Retain Azure feed read-only until all consumers are verified.

18.3 Generic package upload

Use:
The script uploads each file and a .sha256 companion.

19. Container image migration

For each image/tag required:
Prefer digests and immutable version tags. Verify:
Registry manifests can differ due to registry naming; verify image configuration/layers and run the destination image. Do not migrate only latest.

20. Environment and deployment migration

For each Azure environment capture:
  • target endpoints/cluster/server;
  • deployment account;
  • approvals/checks;
  • exclusive locks;
  • health verification;
  • rollback;
  • notifications;
  • maintenance windows.
GitLab deployment job pattern:
Production on GitLab Free:
  • use when: manual and manual_confirmation;
  • restrict job to protected tags/default branch;
  • keep deploy credentials protected;
  • keep Maintainer access very limited;
  • record approval in Jira.
GitLab’s stronger protected-environment authorization is a paid-tier capability; do not claim the Free control is equivalent.

21. Jira integration during migration

Standardize before cutover:
  • branch names include Jira key;
  • commit messages include Jira key;
  • merge request title/description includes Jira key;
  • deployment/release notes list Jira keys.
Test the Jira development panel with:
  1. a branch;
  2. commit;
  3. merge request;
  4. pipeline/deployment where supported by the integration configuration.
Do not migrate Azure Boards items into GitLab simply to duplicate Jira.

22. Dual-run validation

For the pilot and high-risk repositories, run Azure and GitLab from the same source commit. Compare:
  • compiler/runtime/tool versions;
  • test count and pass/fail;
  • generated package names and contents;
  • dependency resolution;
  • code signatures;
  • environment variables;
  • deployment outcome;
  • health checks;
  • release notes;
  • elapsed time;
  • resource use.
Reproducible builds may still differ because of timestamps, signing and environment metadata. Define which differences are acceptable and verify functional/content identity.

23. Cutover procedure per repository

T-5 business days

  • announce freeze/cutover time;
  • complete GitLab pipeline acceptance;
  • confirm access and Jira integration;
  • confirm secret recreation;
  • confirm rollback to Azure;
  • list active branches/PRs;
  • lower risk by finishing or deferring active work.

T-1 day

  • take Azure inventory snapshot;
  • confirm migration operator credentials;
  • confirm GitLab backup/health;
  • verify destination project remains controlled;
  • run rehearsal mirror and validation;
  • confirm developers understand the remote switch.

T0 freeze

  1. stop merges/pushes in Azure by policy/communication;
  2. record final Azure default branch SHA;
  3. run final mirror including LFS;
  4. run verify-repo-migration.sh;
  5. make clean clone from GitLab;
  6. run build/test;
  7. validate submodules;
  8. set/protect default branch;
  9. enable GitLab pipeline;
  10. run required pipeline;
  11. update documentation/badges/webhooks;
  12. declare GitLab canonical;
  13. keep Azure read-only.

Developer remote switch

In an existing working clone:
After the retention period and only when approved:
Developers with local branches must verify each branch’s upstream.

24. Optional temporary reverse mirror

After GitLab becomes canonical, GitLab Free supports push mirroring from GitLab to another Git repository. This may maintain an Azure read-only safety copy during a short transition. Conditions:
  • GitLab is clearly canonical;
  • nobody pushes directly to the Azure mirror;
  • credentials are narrowly scoped and time-limited;
  • mirror status is monitored;
  • the mirror is removed after the approved period.
GitLab pull mirroring from Azure is a paid-tier feature, so the Free migration uses scripted mirror pulls/final sync while Azure is canonical.

25. Rollback before canonical cutover

If verification fails before cutover:
  1. keep Azure canonical;
  2. reopen Azure writes if they were frozen;
  3. archive/delete the incomplete GitLab target as approved;
  4. correct repository/pipeline/secret issues;
  5. schedule another rehearsal.

26. Rollback after canonical cutover

A return to Azure after GitLab has accepted new commits is not a simple toggle. If required:
  1. declare a migration incident;
  2. freeze GitLab writes;
  3. identify commits/tags created after cutover;
  4. mirror GitLab back to a new/controlled Azure repository or approved target;
  5. verify refs/LFS;
  6. validate Azure pipeline and credentials;
  7. explicitly declare the new canonical source;
  8. prevent divergent writes;
  9. preserve both audit histories.
Never allow both systems to accept independent writes.

27. Repository acceptance checklist

  • Azure repository inventoried.
  • Destination namespace/project approved.
  • Access mapped.
  • All branches/tags match.
  • Default branch SHA matches.
  • Git LFS fetched, pushed and checked.
  • Submodules resolve to accessible destinations.
  • Clean GitLab clone succeeds.
  • Local build/test succeeds.
  • GitLab pipeline matches required Azure behaviour.
  • Variables and secrets recreated securely.
  • Package feeds/images migrated where required.
  • Test deployment succeeds.
  • Rollback succeeds or is demonstrated.
  • Jira development link works.
  • Active PR disposition recorded.
  • Azure set read-only/retained.
  • GitLab declared canonical.
  • Developers changed remotes.
  • Documentation updated.

28. Migration evidence packet

Attach to the Jira migration ticket:
Do not attach secret values or credential-bearing URLs.

29. Official references