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_memberskeeps 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 theBlockSeatOveragesrules: 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, likeImportProjectTeamService#check_seats!. A new publicBlockSeatOverages.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 andmapped_without_membership_countcounts) to theimporterlog. - Behind the
gitlab_com_deriskflagfile_import_enterprise_user_mapping, off by default. - Docs:
doc/user/project/settings/import_export.mddescribes 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
- Sign in as an administrator and create a top-level group
ent-rootwith a subgroupent-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 - Create three users:
owner(non-admin),ent-userandplain-user. Makeownera direct Owner ofent-root. Makeent-useran Enterprise user ofent-root:User.find_by_username('ent-user').user_detail.update!(enterprise_group_id: root.id) - As an administrator, create a source project in another group. Add
ent-userandplain-useras 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
- Sign in as
ownerand import the archive intoent-root/target(New project > Import project > GitLab export). - Confirm in the imported project:
- Manage > Members lists
ent-useras a Developer, and does not listplain-user. - The issue created by
ent-useris authored byent-user. The issue created byplain-useris authored byowner.
- Manage > Members lists
- Confirm
log/importer.logcontains one line"message":"[Project/Group Import] Mapped exported member to enterprise user"withgl_user_id=ent-user's id. It also contains oneEnterprise user mapping summaryline 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-rootonly through a group share: invite another group at the Owner role, and make the importer an Owner of that group. ent-useris 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-roothas 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)
- As an administrator, import the archive into
ent-root/targetwith the flag on and again with it off. In both imports,ent-userandplain-userare 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.