Map enterprise users in file-based imports for group Owners

What does this MR do and why?

On GitLab.com, a file-based import (project, group, or single-relation import) maps exported members to existing users only when an administrator runs it. Any other importer gets no members, and every contribution is assigned to the importer. Migrations led by Professional Services therefore need a GitLab staff admin token to keep authorship.

This MR lets a non-admin direct Owner of a top-level group keep authorship for Enterprise users of that group:

  • An EE override of Gitlab::ImportExport::MembersMapper#determine_exported_members keeps only exported members whose email matches an Enterprise user of the importable's root group who is active or deactivated and not a bot. Blocked, banned and pending-approval users are not mapped. The CE mapper then creates those members and maps their contributions as it does today.
  • Every other exported member keeps today's non-admin behaviour: no membership is created, and their contributions fall back to the importer.
  • Gate, in order: admin → CE path, unchanged; feature flag (actor: root group); root is a group; domain_verification_available? (GitLab.com, root group, Premium); importer is a direct Owner of the root group (not through a group share).
  • When a project is imported into a group with Users cannot be added to projects in this group turned on (membership lock applies to project imports only), the Enterprise users are still mapped, so contributions keep their author, but none of their memberships are created. Logged as mapping_path: 'membership_locked'.
  • When the root group blocks seat overages (BlockSeatOverages.block_seat_overages?) and the new billable memberships don't fit in the purchased seats, the same applies: mapped, no memberships, mapping_path: 'seat_limit_exceeded'. Seats are counted with the BlockSeatOverages rules: non-billable roles (Minimal Access, Guest on Ultimate), deactivated users (billing counts only active users), and users already billable in the root group need no seat. It's all-or-nothing, like ImportProjectTeamService#check_seats!. A new public BlockSeatOverages.non_billable_member? exposes the existing non-billable rules.
  • Users already members of the importable stay as they are. The importer's own default membership is unchanged.
  • On the membership-lock and seat-limit paths, mapped users without a membership can still be named on imported relations (for example protected branch push access levels, assignees and reviewers). That grants nothing until an Owner adds them as members.
  • Kept member hashes are cut down to safe keys, so a tampered archive cannot create access requests, invites or LDAP overrides. The email is rewritten to the destination user's stored email, so a case mismatch in the archive still maps.
  • Each mapping logs one line, and each mapper logs one summary (mapping_path, exported, mapped, skipped and mapped_without_membership_count counts) to the importer log.
  • Behind the gitlab_com_derisk flag file_import_enterprise_user_mapping, off by default.
  • Docs: doc/user/project/settings/import_export.md describes the Enterprise-user exception.

Not in scope: placeholder users or user contribution mapping for file imports, Direct Transfer, Offline Transfer, non-enterprise users, admin-path changes, and member audit events on import (admins also skip them today).

Security notes
  • The archive is user-editable. A root-group Owner can attribute imported content to any active or deactivated, non-bot Enterprise user of their own group. This was accepted as a product decision, and the per-mapping log line is the mitigation.
  • Tenant isolation: the lookup is scoped to root.enterprise_users, so Enterprise users of other groups and non-enterprise users are never mapped.
  • Access levels stay capped by CE (Owner for groups, Maintainer for projects).
  • Logs contain ids only, no emails.

References

Screenshots or screen recordings

Not applicable: backend-only change with no UI.

How to set up and validate locally

These steps need a GDK in simulated SaaS mode (export GITLAB_SIMULATE_SAAS=1, then gdk restart), because domain_verification_available? requires Gitlab.com?. They also need an EE license, because domain_verification is a Premium feature.

Setup

  1. Sign in as an administrator and create a top-level group ent-root with a subgroup ent-root/target. In a Rails console (gdk rails console), give the root group a Premium plan and enable the flag for it:
    root = Group.find_by_full_path('ent-root')
    Feature.enable(:file_import_enterprise_user_mapping)
    root.domain_verification_available? # => true
  2. Create three users: owner (non-admin), ent-user and plain-user. Make owner a direct Owner of ent-root. Make ent-user an Enterprise user of ent-root:
    User.find_by_username('ent-user').user_detail.update!(enterprise_group_id: root.id)
  3. As an administrator, create a source project in another group. Add ent-user and plain-user as Developers, and have each of them create an issue. For both users, set Public email in their profile to their primary email (exports include only public emails). Export the project from Settings > General > Advanced > Export project and download the archive.

Part 1: enterprise users are mapped

  1. Sign in as owner and import the archive into ent-root/target (New project > Import project > GitLab export).
  2. Confirm in the imported project:
    • Manage > Members lists ent-user as a Developer, and does not list plain-user.
    • The issue created by ent-user is authored by ent-user. The issue created by plain-user is authored by owner.
  3. Confirm log/importer.log contains one line "message":"[Project/Group Import] Mapped exported member to enterprise user" with gl_user_id = ent-user's id. It also contains one Enterprise user mapping summary line with "mapping_path":"enterprise_owner", "mapped_members_count":1, "skipped_members_count":1.

Part 2: rejection matrix

Import the same archive again (to a new project path) once for each case below, then restore the setting before the next one. In every case, ent-user is not a member and every issue is authored by the importer.

  • Flag off: Feature.disable(:file_import_enterprise_user_mapping, root). No enterprise log lines are written.
  • The importer is a Maintainer of ent-root (not an Owner). The summary line shows "mapping_path":"none".
  • The importer is an Owner of ent-root only through a group share: invite another group at the Owner role, and make the importer an Owner of that group.
  • ent-user is blocked (Admin > Users > ent-user > Block).

These cases map ent-user without a membership: ent-user is not a member, but authors their own issue.

  • ent-root has Settings > General > Permissions and group features > Users cannot be added to projects in this group turned on. The summary line shows "mapping_path":"membership_locked" and "mapped_without_membership_count":1.

A deactivated ent-user (Admin > Users > ent-user > Deactivate) is mapped and becomes a member, as in Part 1. The seat-limit cases are covered by the specs.

  • The project is imported into the importer's personal namespace instead of ent-root/target.

Part 3: admin path unchanged (regression check)

  1. As an administrator, import the archive into ent-root/target with the flag on and again with it off. In both imports, ent-user and plain-user are members, and each authors their own issue, as before this MR.

The cases without simulated SaaS and without the Premium license can't easily be switched inside one GDK session. They are covered by ee/spec/lib/ee/gitlab/import_export/members_mapper_spec.rb.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Rodrigo Tomonari

Merge request reports

Loading
Loading