Direct transfer - Assign contributions to placeholder users - requirements and design
Context
In the process of mapping users' contributions during import, users are required to set a public email on the source instance and create a corresponding user in the destination with the same email address. If a user from the source instance cannot be matched to a user in the destination due to various reasons, such as the absence of prior creation, email configuration issues, or user inactivity, the import process assigns the importing user as the author or assignee for objects like issues, epics, merge requests, comments, and more.
Problem to solve
The current preparation step for user mapping presents several challenges. It demands substantial coordination from the importing user to ensure the correct configuration of both source and destination users. Additionally, if a user mapping fails, it is impossible to fix it unless another migration is performed.
Proposed Solution
To enhance the user experience, we can use a different user mapping approach. Instead of immediately assigning contributions to real destination users, we can attribute these contributions to placeholder users initially. Subsequently, namespace owners can reassign these contributions to real destination user profiles at their convenience.
To achieve this, the Direct Transfer importer will generate a placeholder user account for each source user with a contribution within the import process. These placeholder users will be linked to the top-level namespace. Several attributes will be assigned to the placeholder user to maintain the connection with the source user, including:
- source_user_id: This unique identifier will be used by the import process to determine if a new placeholder user needs to be created
- source_hostname: The source hostname or domain
- source_email: The source user's public email address to facilitate namespace owners during the reassignment of the contribution.
- source_name: The source user's name to facilitate namespace owners during the reassignment of the contribution
- source_username: The source username to facilitate namespace owners during the reassignment of the contribution.
- source_name: The source user's name to facilitate namespace owners during the reassignment of the contribution.
- import_type: To distinguish which importer created the placeholder
To preserve historical context, the placeholder's name
and username
will resemble the source name
and username
. For example, the placeholder's name can have the structure "Placeholder Source Name" and the placeholder's username structure can be %{source_username}_placeholder_user_%{incremental_number}
To facilitate the reassignment of placeholder user's contributions to real destination users, namespace owners can use the UI to choose the real destination user to whom the placeholder user's contributions will be reassigned. See designs for assignment process: #429299[Direct_transfer_-_Placeholder_users_mapping_flow.png]. The reassignment process will only be finalized after the selected user accepts or rejects the request. Once the user accepts the request, all contributions previously attributed to the placeholder user will be attributed to the selected user.
Within the same UI, namespace owners will have the ability to cancel the request as well. It's important to note that once the user accepts the request, it won't be possible to reverse or rollback the operation.
To prevent the namespace owner from selecting an incorrect user, only members of the namespace will be able to be selected.
Once this issue is fixed, we can remove this comment on the docs: !136246 (merged)
Security requirements
See thread #429299 (comment 1636097793)
- Placeholder users must be unable to be added as members to a project or group, including during the import #429299 (comment 1639089679)
- Users will be a kind of internal user.
- Users must be unable to log in #429299 (comment 1649036275)
- Users must have no permissions granted by our authorization framework #429299 (comment 1638221841)
- Users must be "deactivated" #429299 (comment 1645019277)
Performance requirements
- Mark relevant importers are deferred if
users
table is unhealthy #429299 (comment 1640235092) - Placeholder user records should be deleted when not needed #429299 (comment 1619323994)
- Limit number of users created per import and inform the user of the limit beforehand #429299 (comment 1702208311)
Related links
Documentation about internal users - https://docs.gitlab.com/ee/development/internal_users.html