Post-migration contribution and membership mapping

With post-migration mapping, user contributions and memberships from source instances are initially assigned to placeholder users rather than real users on the destination instance.

Because you can defer assigning to real users, you have time to review the import and reassign contributions to the correct users. This process ensures accurate attribution while maintaining control over the mapping process.

Post-migration user contribution and membership mapping is available by default for migrations from:

• GitLab when using direct transfer
• GitHub
• Bitbucket Server
• Gitea

When you import projects to a personal namespace, user contribution mapping and membership mapping is not supported and all contributions are assigned to the personal namespace owner. These contributions cannot be reassigned.

Prerequisites

• Plan for the number of users, according to the user limits.
• If you import to GitLab.com, set up your paid namespace.
• If you import to GitLab.com and use SAML SSO for GitLab.com groups, ensure all users link their SAML identity to their GitLab.com account.

Post-migration mapping workflow

When using post-migration mapping, GitLab maps any memberships and contributions you import to placeholder users. Placeholder users are created on the destination instance even if users with the same email addresses exist on the destination instance. Until you reassign contributions on the destination instance, all contributions are associated with placeholder users.

After the import is complete and you’ve reviewed the results, you can update the mappings as follows:

• Reassign memberships and contributions to existing users on the destination instance. You can map memberships and contributions for users with different email addresses on source and destination instances.
• Create new users on the destination instance and reassign memberships and contributions to them.

You can also keep certain contributions assigned to placeholder users to preserve historical context.

When you reassign contributions to a user on the destination instance, the user can either:

• Accept the reassignment. The reassignment process might take a few minutes. In subsequent imports from the same source instance to the same top-level group or subgroup on the destination instance, contributions are mapped automatically to the user.
• Reject the reassignment.

Enterprise users

If your top-level group has at least one enterprise user, you can reassign contributions only to enterprise users in your organization.

This means you cannot accidentally reassign to users outside your organization.

Deleted users

Contributions on the source instance that were made by a now deleted user are mapped on the destination instance to a ghost user, except when:

• The contribution was never properly detached from the deleted user on the source instance.
• Migrating from Bitbucket Server.

Placeholder users

With contribution and membership mapping, you don’t immediately assign contributions and memberships to users on the destination instance. Instead, a placeholder user is created for any active, inactive, or bot user with imported contributions or memberships.

Both contributions and memberships are initially assigned to these placeholder users and can be reassigned after import to existing users on the destination instance.

Until they are reassigned, contributions are associated with the placeholder. Placeholder memberships do not display in member lists.

Placeholder users do not count towards license limits.

Exceptions

A placeholder user is not created in these scenarios:

• You’re importing a project from Gitea with contributions from deleted users. Contributions from these users are mapped to the user who imported the project.
• You have exceeded your placeholder user limit. Contributions from any new users are mapped to an import user.

Placeholder user attributes

Placeholder users are different to regular users and cannot:

• Sign in.
• Perform any actions. For example, running pipelines.
• Appear in suggestions as assignees or reviewers for issues and merge requests.
• Be members of projects and groups.

To maintain a connection with a user on a source instance, placeholder users have:

• A unique identifier (source_user_id) used by the import process to determine if a new placeholder user is required.
• A source hostname or domain (source_hostname).
• A source user’s name (source_name) to help with reassignment of contributions.
• A source user’s username (source_username) to facilitate group owners during the reassignment of the contribution.
• An import type (import_type) to distinguish which importer created the placeholder.
• A timestamp of when the source user was created (created_at) in local time for migration tracking (introduced in GitLab 17.10).

To preserve historical context, the placeholder user name and username are derived from the source user name and username:

• Placeholder user’s name is Placeholder <source user name>.
• Placeholder user’s username is %{source_username}_placeholder_user_%{incremental_number}.

View placeholder users

Prerequisites:

• You must have the Owner role for the group.

Placeholder users are created on the destination instance while a group or project is imported. To view placeholder users created during imports to a top-level group and its subgroups:

1. In the top bar, select Search or go to and find your group. This group must be at the top level.
2. Select Manage > Members.
3. Select the Placeholders tab.

Filter for placeholder users

Prerequisites:

• You must have administrator access to the instance.

Placeholder users are created on the destination instance while a group or project is imported. To filter for placeholder users created during imports for an entire instance:

1. In the upper-right corner, select Admin.
2. Select Overview > Users.
3. In the search box, filter users by type.

Creating placeholder users

Placeholder users are created per import source and per top-level group:

• If you import the same project twice to the same top-level group on the destination instance, the second import uses the same placeholder users as the first import.
• If you import the same project twice, but to a different top-level group on the destination instance, the second import creates new placeholder users under that top-level group.

When a user accepts the reassignment, subsequent imports from the same source instance to the same top-level group or subgroup on the destination instance do not create placeholder users. Instead, contributions are mapped automatically to the user.

Placeholder user deletion

When you delete a top-level group that contains placeholder users, these users are automatically scheduled for removal. This process might take some time to complete. However, placeholder users remain in the system if they’re also associated with other projects or groups.

Placeholder user limits

If importing to GitLab.com, placeholder users are limited per top-level group on the destination instance. The limits differ depending on your plan and seat count. Placeholder users do not count towards license limits.

For GitLab Self-Managed and GitLab Dedicated, no placeholder limits apply by default. A GitLab administrator can set a placeholder limit on their instance.

To view your current placeholder user usage and limits:

1. In the top bar, select Search or go to and find your group. This group must be at the top level.
2. Select Settings > Usage quotas.
3. Select the Import tab.

You cannot determine the number of placeholder users you need in advance.

When the placeholder user limit is reached, all contributions are assigned to a single non-functional user called Import User. Contributions assigned to Import User might be deduplicated, and some contributions might not be created during the import. For example, if multiple approvals from a merge request approver are assigned to Import User, only the first approval is created and the others are ignored. The contributions that might be deduplicated are:

• Approval rules
• Emoji reactions
• Issue assignees
• Memberships
• Merge request approvals, assignees, and reviewers
• Push, merge request, and deploy access levels

Every change creates a system note, which is not affected by the placeholder user limit.

Alternative mapping method

An alternative to post-migration mapping is a method that maps during a migration. This method is not recommended, and any problems found are unlikely to be fixed.

The alternative method of mapping:

• Requires some preparation before migration, including disabling feature flags.
• Is available for migrations from:
  • GitHub.
  • Bitbucket Server.
  • Gitea (for GitLab 18.5 and earlier).
• Is available for migrations to GitLab Self-Managed and GitLab Dedicated.

For more information, see the alternative method of mapping documentation for each importer.