Map ADO access levels to GitLab roles during migration

Overview

During migration, assign GitLab membership roles to migrated users based on their Azure DevOps (ADO) access level. Use the mapped role when:

• generating the export (tar) and seeding memberships, and
• running post-migration reconciliation to enforce/repair memberships.

Project administrators should receive Owner-level permissions.

Role mapping:

• ADO Basic, MSDN → GitLab Developer
• ADO Project Administrator → GitLab Owner
• ADO Stakeholder → GitLab Guest

Reference: https://learn.microsoft.com/en-us/azure/devops/organizations/security/access-levels?view=azure-devops#programmatic-mapping-of-access-levels

Data model

• Add a per-member field indicating the target GitLab role.
• Field name: gitlab_role
• Allowed values: Owner, Developer, Reporter
• Allow manual change (in json) per available roles (including custom?)

Example of json:

[
  {
    "name": "gitlab-ps-sandbox",
    "path": "gitlab-ps-sandbox",
    "members": [
      {
        "username": "frantisek.kupka",
        "email": "frantisek.kupka@gitlabpsoutlook.onmicrosoft.com",
        "gitlab_role": "Developer"
      },
      {
        "username": "fiodor.dostoevskii",
        "email": "fiodor.dostoevskii@gitlabpsoutlook.onmicrosoft.com",
        "gitlab_role": "Owner"
      }
    ]
  }
]

Behavior

• Enrichment: derive gitlab_role from each user’s ADO access level per mapping; allow per-user override if already present.
• Export: include gitlab_role in the tar and seed members with that role.
• Post-migration: reconcile actual GitLab memberships to match gitlab_role for all staged members.
• Existing higher privileges: do not downgrade an existing member unless a force flag is set (see Flags).
• Unmapped/unknown ADO levels: log a warning; default to Reporter unless a configurable default is provided.

Configuration and flags

• Enable/disable mapping:
  • CLI: --skip-role-mapping to disable
• Force reconciliation (allow downgrades): --force-role-reconcile (default: off)

Tasks

• Update docs if needed (workflow, runbooks, README, migration metrics, etc.)

Acceptance Criteria

• Given ADO Basic/MSDN users, they are created/updated as GitLab Developers.
• Given ADO Stakeholder users, they are created/updated as GitLab Reporters.
• Given ADO Project Administrators, they receive Owner-equivalent permissions per the Notes.
• Export contains gitlab_role for all mapped users when mapping is enabled.
• Post-migration job sets or fixes memberships to match gitlab_role.
• With --skip-role-mapping, no gitlab_role is added and no membership changes are performed due to mapping.
• With --force-role-reconcile, users with higher roles are downgraded to the mapped role; without it, higher roles are preserved and logged.
• Existing UTs pass locally.
• 100% code coverage on new code.

@gitlab-org/professional-services-automation/tools/migration