From 2ec81ffb319c232df43fd9ef26b4289a5f7f1fb4 Mon Sep 17 00:00:00 2001 From: Luke Duncalfe <lduncalfe@gitlab.com> Date: Wed, 18 Dec 2024 04:44:28 +0000 Subject: [PATCH] Update importer docs for user contribution mapping GitLab.com has the improved user contribution mapping enabled for GitHub, Bitbucket Server and Gitea importers. This docs change refactors these importers to have a common section, and updates old information regarding user mapping to signal this is available on Self-managed and Dedicated only now. https://gitlab.com/groups/gitlab-org/-/epics/14667 --- doc/user/project/import/bitbucket_server.md | 25 ++++---- doc/user/project/import/gitea.md | 22 ++++--- doc/user/project/import/github.md | 66 +++++++++++++-------- 3 files changed, 67 insertions(+), 46 deletions(-) diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 2a588c8b61ad8..12985a4fff0c3 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -17,11 +17,6 @@ DETAILS: Import your projects from Bitbucket Server to GitLab. -WARNING: -Importing from Bitbucket Server to GitLab.com is [unavailable](https://status.gitlab.com). -For more information, contact [GitLab Support](https://about.gitlab.com/support/). -[Importing from Bitbucket Cloud](bitbucket.md) is not affected. - ## Prerequisites > - Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. @@ -90,18 +85,26 @@ The following items are changed when they are imported: - Project filtering doesn't support fuzzy search. Only **starts with** or **full match** strings are supported. -## User assignment +## User contribution mapping > - User mapping by email address or username [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36885) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default. > - Mapping user mentions to GitLab users [added](https://gitlab.com/gitlab-org/gitlab/-/issues/433008) in GitLab 16.8. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/153041) to map users only by email address in GitLab 17.1. +> - [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [User contribution and membership mapping](../import/index.md#user-contribution-and-membership-mapping) in 17.8. + +The Bitbucket Server importer uses [an improved method](../import/index.md#user-contribution-and-membership-mapping) +of mapping user contributions for: + +- GitLab.com +- GitLab self-managed 17.7 or later when the `importer_user_mapping` and `bitbucket_server_user_mapping` feature flags are enabled. + +### Old method of user contribution mapping -FLAG: -The availability of this feature is controlled by a feature flag. -For more information, see the history. +You can use the old user contribution mapping method for imports to GitLab self-managed and GitLab Dedicated instances. For imports to GitLab.com, you must +use [the improved method](../import/index.md#user-contribution-and-membership-mapping) instead. -When issues and pull requests are importing, the importer tries to match a Bitbucket Server user's email address -with a confirmed email address in the GitLab user database. If no such user is found: +Using the old method, the importer tries to match a Bitbucket Server user's email address with a confirmed email address in the GitLab user database. If no +such user is found: - The project creator is used instead. The importer appends a note in the comment to mark the original creator. - For pull request reviewers, no reviewer is assigned. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index a26c77fc5f968..392564bd5d7ec 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -16,10 +16,6 @@ DETAILS: Import your projects from Gitea to GitLab. -WARNING: -Importing from Gitea to GitLab.com is [unavailable](https://status.gitlab.com). -For more information, contact [GitLab Support](https://about.gitlab.com/support/). - The Gitea importer can import: - Repository description @@ -95,9 +91,17 @@ You also can: ## User contribution mapping -User contributions are assigned to the project creator (usually the user who started the import process) by default. -This method of user contribution mapping is available for GitLab self-managed without enabled feature flags. +> - [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [User contribution and membership mapping](../import/index.md#user-contribution-and-membership-mapping) in 17.8. + +The Gitea importer uses [an improved method](../import/index.md#user-contribution-and-membership-mapping) +of mapping user contributions for: + +- GitLab.com +- GitLab self-managed 17.6 or later when the `importer_user_mapping` and `gitea_user_mapping` feature flags are enabled. + +### Old method of user contribution mapping + +You can use the old user contribution mapping method for imports to GitLab self-managed and GitLab Dedicated instances. For imports to GitLab.com, you must +use [the improved method](../import/index.md#user-contribution-and-membership-mapping) instead. -For information on the other method available for GitLab self-managed -with enabled feature flags and for GitLab.com, -see [user contribution and membership mapping](../../project/import/index.md#user-contribution-and-membership-mapping). +Using the old method, user contributions are assigned to the project creator (usually the user who started the import process) by default. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 0a693c2c956a1..9bbccd1581989 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -17,10 +17,6 @@ DETAILS: You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not migrate or import any types of groups or organizations from GitHub to GitLab. -WARNING: -Importing from GitHub to GitLab.com is [unavailable](https://status.gitlab.com). -For more information, contact [GitLab Support](https://about.gitlab.com/support/). - Imported issues, merge requests, comments, and events have an **Imported** badge in GitLab. The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or @@ -66,7 +62,13 @@ on the GitLab instance you import to. ### Accounts for user contribution mapping -For user contribution mapping between GitHub and GitLab to work: +> - [Preparation requirement removed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) in GitLab 17.8. + +Before using [the old method of user contribution mapping](#old-method-of-user-contribution-mapping) for imports to GitLab self-managed and GitLab +Dedicated, you must take meet certain requirements. Imports to GitLab.com use [an improved method](../import/index.md#user-contribution-and-membership-mapping) +that doesn't require preparation. + +These requirements are: - Each GitHub author and assignee in the repository must have a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). @@ -75,18 +77,6 @@ For user contribution mapping between GitHub and GitLab to work: GitHub Enterprise does not require a public email address, so you might have to add it to existing accounts. -If the above requirements are not met, the importer can't map the particular user's contributions. In that case: - -- The project creator is set as the author and assignee of issues and merge requests. The project creator is usually the - user that initiated the import process. For some contributions that have a description or note such as pull requests, - issue, notes, the importer amends the text with details of who originally created the contribution. -- Reviewers and approvals added on pull requests in GitHub cannot be imported. In this case, the importer creates comments - describing that non-existent users were added as reviewers and approvers. However, the actual reviewer status and - approval are not applied to the merge request in GitLab. - -[In GitLab 17.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/477553), GitLab adds backticks to username mentions in issues, merge requests, and notes. -These backticks prevent linking to an incorrect user with the same username on the GitLab instance. - ## Known issues - GitHub pull request comments (known as diff notes in GitLab) created before 2017 are imported in separate threads. @@ -108,15 +98,6 @@ These backticks prevent linking to an incorrect user with the same username on t ## Import your GitHub repository into GitLab -Before you begin, ensure that any GitHub user you want to map to a GitLab user -has a GitLab email address that matches their -[publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) -on GitHub. - -If a GitHub user's public email address doesn't match any GitLab user email -address, the user's activity is associated with the user account that is -performing the import. - You can import your GitHub repository by either: - [Using GitHub OAuth](#use-github-oauth) @@ -257,6 +238,39 @@ After imports are completed, they can be in one of three states: Expand **Details** to see a list of [repository entities](#imported-data) that failed to import. +## Username mentions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/477553) in GitLab 17.5. + +GitLab adds backticks to username mentions in issues, merge requests, and notes. +These backticks prevent linking to an incorrect user with the same username on the GitLab instance. + +## User contribution mapping + +> - [Changed on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/14667) to [User contribution and membership mapping](../import/index.md#user-contribution-and-membership-mapping) in 17.8. + +The GitHub importer uses [an improved method](../import/index.md#user-contribution-and-membership-mapping) +of mapping user contributions for: + +- GitLab.com +- GitLab self-managed 17.6 or later when the `importer_user_mapping` and `github_user_mapping` feature flags are enabled. + +### Old method of user contribution mapping + +You can use the old user contribution mapping method for imports to GitLab self-managed and GitLab Dedicated instances. For imports to GitLab.com, you must +use [the improved method](../import/index.md#user-contribution-and-membership-mapping) instead. + +Using the old method, when [user accounts are provisioned correctly](#accounts-for-user-contribution-mapping), users are mapped during the import. + +If the requirements are not met, the importer can't map the particular user's contributions. In that case: + +- The project creator is set as the author and assignee of issues and merge requests. The project creator is usually the + user that initiated the import process. For some contributions that have a description or note such as pull requests, + issue, notes, the importer amends the text with details of who originally created the contribution. +- Reviewers and approvals added on pull requests in GitHub cannot be imported. In this case, the importer creates comments + describing that non-existent users were added as reviewers and approvers. However, the actual reviewer status and + approval are not applied to the merge request in GitLab. + ## Mirror a repository and share pipeline status DETAILS: -- GitLab