> ## Documentation Index
> Fetch the complete documentation index at: https://deployment.naudecoreventures.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps to NCV GitLab Migration Guide

> Repository, LFS, pipeline, package, variable and cutover migration

# Azure DevOps to NCV GitLab Migration Guide

## 1. Scope

This guide migrates engineering delivery from Azure DevOps Services to:

```text theme={null}
https://code.naudecoreventures.com
```

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:

| Wave | Content | Purpose |
| - | - | - |
| 0 | GitLab platform and CI templates | Prepare destination and governance |
| 1 | One low-risk pilot repository | Prove repository, pipeline, Jira, package and release flow |
| 2 | Standard libraries/services | Repeatable migration without production deployment risk |
| 3 | Customer-facing applications | Full test/release/updater validation |
| 4 | Production backend/deployment repositories | Highest deployment and credential risk |
| 5 | Archives and retained read-only repositories | Close-out and evidence |

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:

```bash theme={null}
az extension add --name azure-devops
az devops configure --defaults \
  organization=https://dev.azure.com/<organization> \
  project='<project>'

az repos list --output table
az pipelines list --output table
az pipelines variable-group list --output table
az artifacts universal list \
  --organization https://dev.azure.com/<organization> \
  --feed <feed> 2>/dev/null || true
```

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:

```text theme={null}
ncv/products/<project>
```

For customer-download releases:

```text theme={null}
ncv-releases/<product>
```

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:

```bash theme={null}
git ls-remote --symref <AZURE_URL> HEAD
git ls-remote --heads <AZURE_URL> | sort
git ls-remote --tags <AZURE_URL> | sort
```

## 8.2 Mirror the repository

Use the supplied script:

```bash theme={null}
./scripts/migrate-azure-repo.sh \
  '<AZURE_REPO_URL>' \
  'git@code.naudecoreventures.com:ncv/products/<project>.git' \
  '/secure/migration-work/<project>'
```

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

```bash theme={null}
./scripts/verify-repo-migration.sh \
  '<AZURE_REPO_URL>' \
  'git@code.naudecoreventures.com:ncv/products/<project>.git'
```

This compares:

* branches;
* tags;
* default branch;
* default HEAD SHA.

Also make a clean clone:

```bash theme={null}
rm -rf /tmp/<project>-gitlab-test
git clone --recurse-submodules \
  'git@code.naudecoreventures.com:ncv/products/<project>.git' \
  /tmp/<project>-gitlab-test
cd /tmp/<project>-gitlab-test
git lfs pull
git lfs fsck
git submodule status --recursive
```

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

| Azure DevOps | GitLab equivalent |
| - | - |
| `azure-pipelines.yml` | `.gitlab-ci.yml` |
| Stage | Stage |
| Job | Job |
| Step/task | `script`, `before_script`, `after_script`, component/template |
| Microsoft-hosted agent | Hosted runner (not used initially) |
| Self-hosted agent pool | Self-managed GitLab Runner and tags |
| `pool` / demands | runner tags and platform-specific runners |
| Variables | CI/CD variables |
| Variable group | group/project CI/CD variables or secret manager |
| Secure file | file-type CI/CD variable or protected secret-file workflow |
| Service connection | protected CI credentials, OIDC/workload identity where supported |
| Pipeline artifact | GitLab job artifact |
| Azure Artifacts feed | GitLab Package Registry or retained external repository |
| Environment | GitLab environment |
| Deployment job | deploy job with `environment`, `resource_group`, rules |
| Approval/check | manual job; stronger protected-environment controls require paid tier |
| Template repository | versioned GitLab `include:project` template |
| `condition` | `rules` / `when` / `needs` |
| `dependsOn` | `needs` / stage ordering |
| Schedule | GitLab pipeline schedule |
| Build number | `CI_PIPELINE_IID`, tag or controlled version |
| Release pipeline | GitLab deployment/release jobs |
| Retention | `artifacts:expire_in`, package/image policy |

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

```yaml theme={null}
trigger:
  branches:
    include:
      - main
pr:
  branches:
    include:
      - main
```

GitLab equivalent pattern:

```yaml theme={null}
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_TAG'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    - when: never
```

Path filters convert to `rules:changes`:

```yaml theme={null}
service:test:
  script:
    - ./gradlew test
  rules:
    - changes:
        - service/**/*
        - build.gradle.kts
```

Validate whether a monorepo job must run on dependency/config changes outside its immediate directory.

## 12. Agent pool conversion

Azure:

```yaml theme={null}
pool:
  vmImage: windows-latest
```

GitLab:

```yaml theme={null}
windows:build:
  tags:
    - windows-x64
  script:
    - flutter build windows --release
```

NCV runner tags:

```text theme={null}
linux-small
windows-x64
macos-arm64
```

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:

| Azure variable type | GitLab handling |
| - | - |
| Normal value | Project/group variable or checked-in non-secret config |
| Secret | Masked variable |
| Production-only secret | Protected + masked variable |
| Certificate/private key file | Protected file-type variable |
| Shared secret | Narrowest applicable group variable |
| Key Vault-backed secret | Prefer retaining secret-manager retrieval/workload identity |

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:

```yaml theme={null}
- task: Cache@2
  inputs:
    key: 'gradle | "$(Agent.OS)" | **/gradle-wrapper.properties'
    path: $(GRADLE_USER_HOME)
```

GitLab:

```yaml theme={null}
cache:
  key:
    files:
      - gradle/wrapper/gradle-wrapper.properties
  paths:
    - .gradle/caches/
    - .gradle/wrapper/
```

### Publish test results

Azure:

```yaml theme={null}
- task: PublishTestResults@2
  inputs:
    testResultsFiles: '**/TEST-*.xml'
```

GitLab:

```yaml theme={null}
artifacts:
  when: always
  reports:
    junit:
      - '**/build/test-results/test/*.xml'
```

### Publish pipeline artifact

Azure:

```yaml theme={null}
- publish: build/output
  artifact: application
```

GitLab:

```yaml theme={null}
artifacts:
  paths:
    - build/output/
  expire_in: 14 days
```

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:

| Azure feed content | Destination |
| - | - |
| Maven packages | GitLab Maven Package Registry |
| npm packages | GitLab npm Package Registry |
| NuGet packages | GitLab NuGet Package Registry |
| PyPI packages | GitLab PyPI Package Registry |
| arbitrary EXE/ZIP/AppImage | GitLab Generic Packages |
| container images | GitLab Container Registry |
| Universal Packages | Generic Packages after metadata/naming review |
| Debian/RPM repository semantics | Not natively supported as apt/yum repository; retain/add dedicated repository service or store only as generic downloads |

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:

```bash theme={null}
GITLAB_TOKEN='<temporary-project-token>' \
./scripts/publish-generic-package.sh \
  '<PROJECT_ID>' '<PACKAGE_NAME>' '<VERSION>' <files...>
```

The script uploads each file and a `.sha256` companion.

## 19. Container image migration

For each image/tag required:

```bash theme={null}
docker login <AZURE_REGISTRY>
docker pull <AZURE_REGISTRY>/<image>:<tag>

docker login registry.code.naudecoreventures.com
docker tag \
  <AZURE_REGISTRY>/<image>:<tag> \
  registry.code.naudecoreventures.com/<group>/<project>/<image>:<tag>
docker push \
  registry.code.naudecoreventures.com/<group>/<project>/<image>:<tag>
```

Prefer digests and immutable version tags. Verify:

```bash theme={null}
docker image inspect <source> --format '{{index .RepoDigests 0}}'
docker image inspect <destination> --format '{{index .RepoDigests 0}}'
```

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:

```yaml theme={null}
deploy:test:
  stage: deploy_test
  resource_group: my-service-test
  environment:
    name: test
    url: https://test.example.com
  script:
    - ./deploy.sh "$CI_COMMIT_SHA"
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

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:

```bash theme={null}
git remote -v
git remote rename origin azure
git remote add origin \
  git@code.naudecoreventures.com:ncv/products/<project>.git
git fetch origin --prune --tags
git branch --set-upstream-to=origin/main main
git remote -v
```

After the retention period and only when approved:

```bash theme={null}
git remote remove azure
```

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:

```text theme={null}
Repository:
Azure URL:
GitLab URL:
Migration date/time:
Migration operator:
Final Azure default SHA:
Final GitLab default SHA:
Branch/tag comparison result:
LFS result:
Submodule result:
Clean clone result:
Azure pipeline reference:
GitLab pipeline reference:
Test/deployment evidence:
Secrets recreated by:
Active PR disposition:
Cutover approver:
Rollback point:
Azure retention end date:
Known differences:
```

Do not attach secret values or credential-bearing URLs.

## 29. Official references

* Microsoft: import a Git repository and handle LFS: [https://learn.microsoft.com/azure/devops/repos/git/import-git-repository](https://learn.microsoft.com/azure/devops/repos/git/import-git-repository)
* Azure Pipelines concepts: [https://learn.microsoft.com/azure/devops/pipelines/](https://learn.microsoft.com/azure/devops/pipelines/)
* Azure variable groups: [https://learn.microsoft.com/azure/devops/pipelines/library/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/](https://docs.gitlab.com/user/project/import/repo_by_url/)
* GitLab repository mirroring: [https://docs.gitlab.com/user/project/repository/mirror/](https://docs.gitlab.com/user/project/repository/mirror/)
* GitLab CI/CD: [https://docs.gitlab.com/ci/](https://docs.gitlab.com/ci/)
* GitLab Package Registry: [https://docs.gitlab.com/user/packages/package\_registry/](https://docs.gitlab.com/user/packages/package_registry/)
* GitLab Generic Packages: [https://docs.gitlab.com/user/packages/generic\_packages/](https://docs.gitlab.com/user/packages/generic_packages/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.