Azure DevOps to NCV GitLab Migration Guide
1. Scope
This guide migrates engineering delivery from Azure DevOps Services to:- 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.
2. Key migration truths
- A Git mirror moves Git commits, branches, tags, and refs.
- Git LFS objects require an explicit fetch/push step.
- Azure pull-request discussions, approvals, pipeline history, logs, and work items do not become GitLab merge requests/pipelines through a Git mirror.
- Pipeline YAML must be translated from Azure syntax to GitLab CI syntax.
- Azure Classic pipelines must be documented and rewritten; there is no reliable one-click conversion.
- Secrets must be recreated, not copied into YAML or migration logs.
- Azure remains read-only for historical evidence after cutover until the retention decision is approved.
- 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.
5. Inventory
Start withtemplates/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.
6. Destination preparation
Before migrating a repository:- create the GitLab group/project;
- leave the repository empty;
- set visibility to Private;
- set the intended default branch name;
- assign Maintainer/Developer access;
- configure branch/tag protection;
- disable automatic pipeline execution if the imported repository contains untrusted or not-yet-converted
.gitlab-ci.ymlcontent; - create required CI variables without values exposed to developers who do not need them;
- create the Jira link/integration;
- record the GitLab project ID and clone URL.
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.
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.
8.2 Mirror the repository
Use the supplied 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
- branches;
- tags;
- default branch;
- default HEAD SHA.
8.4 Default branch and protection
Confirm in GitLab:- correct default branch;
mainprotected;- 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:- ensure source branch is mirrored;
- create a GitLab merge request;
- link the Azure PR in the description;
- copy only essential context/decisions—not secrets or excessive history;
- ask reviewers to re-approve in GitLab;
- 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:- Write the current pipeline’s behaviour in plain language.
- List triggers, inputs, secrets, agent OS, tasks, artifacts, environments and approvals.
- Separate validation, build, package, deploy and release responsibilities.
- Map to shared GitLab templates.
- Convert one stage at a time.
- Run Azure and GitLab pipelines against the same commit.
- Compare test results, produced files, checksums where reproducible, deployment effects and timing.
- Resolve differences before cutover.
- Disable Azure trigger only after GitLab acceptance.
11. Trigger conversion
Azure example:rules:changes:
12. Agent pool conversion
Azure: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.
13.2 GitLab destination
Use GitLab project or group CI/CD variables:
Secret migration process:
- secret owner retrieves or recreates it through approved vault/provider;
- administrator enters it directly into GitLab UI/secret manager;
- migration engineer does not receive a plaintext spreadsheet;
- run an authentication test;
- rotate the old Azure credential after cutover;
- 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.
- 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.
15. Service connections
For every Azure service connection record:- provider/target;
- identity type;
- permissions;
- environments using it;
- credential expiry;
- owner;
- replacement authentication method.
- workload identity/OIDC with short-lived credentials, when the target supports it;
- dedicated service principal/account with least privilege and rotation;
- protected deploy token/key;
- long-lived static credential only when unavoidable.
16. Azure Pipelines task examples
Cache
Azure:Publish test results
Azure:Publish pipeline artifact
Azure:17. Classic build/release pipelines
For each Classic pipeline:- export screenshots and task definitions;
- document inputs, variable groups, agent pool, tasks, artifacts, approvals, gates, schedules and retention;
- identify scripts hidden in inline task fields;
- move reusable script logic into version-controlled repository files;
- build a GitLab pipeline from tested scripts/templates;
- run in a non-production environment;
- perform a controlled production simulation/approval;
- preserve Azure pipeline read-only for history.
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:.sha256 companion.
19. Container image migration
For each image/tag required: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.
- use
when: manualandmanual_confirmation; - restrict job to protected tags/default branch;
- keep deploy credentials protected;
- keep Maintainer access very limited;
- record approval in Jira.
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.
- a branch;
- commit;
- merge request;
- pipeline/deployment where supported by the integration configuration.
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.
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
- stop merges/pushes in Azure by policy/communication;
- record final Azure default branch SHA;
- run final mirror including LFS;
- run
verify-repo-migration.sh; - make clean clone from GitLab;
- run build/test;
- validate submodules;
- set/protect default branch;
- enable GitLab pipeline;
- run required pipeline;
- update documentation/badges/webhooks;
- declare GitLab canonical;
- keep Azure read-only.
Developer remote switch
In an existing working clone: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.
25. Rollback before canonical cutover
If verification fails before cutover:- keep Azure canonical;
- reopen Azure writes if they were frozen;
- archive/delete the incomplete GitLab target as approved;
- correct repository/pipeline/secret issues;
- 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:- declare a migration incident;
- freeze GitLab writes;
- identify commits/tags created after cutover;
- mirror GitLab back to a new/controlled Azure repository or approved target;
- verify refs/LFS;
- validate Azure pipeline and credentials;
- explicitly declare the new canonical source;
- prevent divergent writes;
- preserve both audit histories.
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:29. Official references
- Microsoft: import a Git repository and handle LFS: https://learn.microsoft.com/azure/devops/repos/git/import-git-repository
- Azure Pipelines concepts: https://learn.microsoft.com/azure/devops/pipelines/
- Azure variable groups: https://learn.microsoft.com/azure/devops/pipelines/library/variable-groups
- GitLab migrate through a Git URL: https://docs.gitlab.com/user/project/import/repo_by_url/
- GitLab repository mirroring: https://docs.gitlab.com/user/project/repository/mirror/
- GitLab CI/CD: https://docs.gitlab.com/ci/
- GitLab Package Registry: https://docs.gitlab.com/user/packages/package_registry/
- GitLab Generic Packages: https://docs.gitlab.com/user/packages/generic_packages/