Merge branch '440353-docs-github-importer-enterprise-clarifications' into 'master'

GitHub importer Clarifications for GH Enterprise See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/143743 Merged-by: Evan Read <eread@gitlab.com> Approved-by: Rodrigo Tomonari <rtomonari@gitlab.com> Approved-by: Evan Read <eread@gitlab.com> Reviewed-by: Evan Read <eread@gitlab.com> Reviewed-by: Luke Duncalfe <lduncalfe@gitlab.com> Reviewed-by: Rodrigo Tomonari <rtomonari@gitlab.com> Co-authored-by: Rodrigo Tomonari <rtomonari@gitlab.com> Co-authored-by: Luke Duncalfe <lduncalfe@gitlab.com> Co-authored-by: Luke Duncalfe <lduncalfe@eml.cc>

Merge branch '440353-docs-github-importer-enterprise-clarifications' into 'master'
1de69f43 · Evan Read · GitLab · 1998d792 · 6e8c2a89 · 1de69f43
--- a/doc/user/project/import/github.md
+++ b/doc/user/project/import/github.md
@@ -20,10 +20,9 @@ migrate or import any types of groups or organizations from GitHub to GitLab.
 The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or
 `gitlab.com/customer-success`.
-If you are importing from GitHub Enterprise to GitLab.com, use the
+Using the GitLab UI, the GitHub importer always imports from the
-[GitLab Import API](../../../api/import.md#import-repository-from-github) GitHub endpoint instead. The API allows you to
+`github.com` domain. If you are importing from a self-hosted GitHub Enterprise Server domain, use the
-provide a different domain to import the project from. Using the UI, the GitHub importer always imports from the
+[GitLab Import API](#use-the-rest-api) GitHub endpoint.
-`github.com` domain.
 When importing projects:
@@ -59,25 +58,9 @@ To import projects from GitHub:
  matching email addresses are required.
 - GitHub accounts must have a GitHub public-facing email address so that all comments and contributions can be properly mapped to
  the same user in GitLab. GitHub Enterprise does not require this field to be populated so you might have to add it on existing accounts.
+- For self-managed GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the
-### Importing from GitHub Enterprise to self-managed GitLab
-If you are importing from GitHub Enterprise to a self-managed GitLab instance:
- You must first enable the [GitHub integration](../../../integration/github.md).
- GitHub must be enabled as an import source in the
-  [Admin Area](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources).
- For GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the
  [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains).
-### Importing from GitHub.com to self-managed GitLab
-If you are importing from GitHub.com to a self-managed GitLab instance:
- You don't need to enable the [GitHub integration](../../../integration/github.md).
- GitHub must be enabled as an import source in the
-  [Admin Area](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources).
 ### Known issues
 - GitHub pull request comments (known as diff notes in GitLab) created before 2017 are imported in separate threads.
@@ -98,30 +81,67 @@ 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.
-### Use the GitHub integration
+You can import your GitHub repository by either:
+- [Using GitHub OAuth](#use-github-oauth)
+- [Using a GitHub Personal Access Token](#use-a-github-personal-access-token)
+- [Using the API](#use-the-rest-api)
+### Use GitHub OAuth
+If you are importing to GitLab.com or to a self-managed GitLab that has GitHub OAuth [configured](../../../integration/github.md), you can use GitHub OAuth to import your repository.
+This method has an advantage over using a [Personal Access Token (PAT)](#use-a-github-personal-access-token) 
+because the backend exchanges the access token with the appropriate permissions.
 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
 1. Select **Import project** and then **GitHub**.
-1. Now you can either:
+1. Select **Authorize with GitHub**.
-   - If GitHub OAuth is [configured](../../../integration/github.md) for the instance, select **Authorize with GitHub**.
+1. Proceed to [selecting which repositories to import](#select-which-repositories-to-import).
-   - Use a GitHub personal access token:
-     1. Go to <https://github.com/settings/tokens/new>.
+To use a different method to perform an import after previously performing
-     1. In the **Note** field, enter a token description.
+these steps, sign out of your GitLab account and sign in again.
-     1. Select the `repo` scope.
-     1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope.
+### Use a GitHub Personal Access Token
-     1. Select **Generate token**.
-     1. On the GitLab import page, in the **Personal Access Token** field, paste the GitHub personal access token.
+To import your GitHub repository using a GitHub Personal Access Token:
-     1. Select **Authenticate**.
-1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import).
+1. Generate a GitHub Personal Access Token:
+    1. Go to <https://github.com/settings/tokens/new>.
-To use a different token to perform an imports after previously performing
+    1. In the **Note** field, enter a token description.
+    1. Select the `repo` scope.
+    1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope.
+    1. Select **Generate token**.
+1. On the GitLab left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
+1. Select **Import project** and then **GitHub**.
+1. Select **Authorize with GitHub**.
+1. In the **Personal Access Token** field, paste the GitHub Personal Access Token.
+1. Select **Authenticate**.
+1. Proceed to [selecting which repositories to import](#select-which-repositories-to-import).
+To use a different token to perform an import after previously performing
 these steps, sign out of your GitLab account and sign in again, or revoke the
 older token in GitHub.
 ### Use the REST API
-You can also import a repository from GitHub using the
+The [GitLab REST API](../../../api/import.md#import-repository-from-github) can be used to import a GitHub repository. It has some advantages over using the GitLab UI:
-[GitLab REST API](../../../api/import.md#import-repository-from-github).
+- Can be used to import GitHub repositories that you do not own if they are public.
+- It can be used to import from a GitHub Enterprise Server that is self-hosted.
+- Can be used to set the `timeout_strategy` option that is not available to the UI.
+The REST API is limited to authenticating with GitLab Personal Access Tokens.
+To import your GitHub repository using the GitLab REST API:
+1. Generate a GitHub Personal Access Token:
+    1. Go to <https://github.com/settings/tokens/new>.
+    1. In the **Note** field, enter a token description.
+    1. Select the `repo` scope.
+    1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope.
+    1. Select **Generate token**.
+1. Use the [GitLab REST API](../../../api/import.md#import-repository-from-github) to import your GitHub repository.
 ### Filter repositories list
@@ -240,25 +260,20 @@ Increasing the number of Sidekiq workers does *not* reduce the time spent clonin
 ### Enable GitHub OAuth using a GitHub Enterprise Cloud OAuth App
-You can use a personal access token to make API requests. Additionally, you can
+If you belong to a [GitHub Enterprise Cloud organization](https://docs.github.com/en/enterprise-cloud@latest/get-started/onboarding) you can configure your self-managed GitLab instance to obtain a higher [GitHub API rate limit](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-authenticated-users).
-authorize a GitHub App or OAuth app, which can then make API requests on your
-behalf.
+GitHub API requests are usually subject to a rate limit of 5,000 requests per hour. Using the steps below, you obtain a higher 15,000 requests per hour rate limit, resulting in a faster overall import time.
-API requests to GitHub are [subject to rate limits](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-authenticated-users).
+Prerequisites:
-For GitHub repositories with tens of thousands of issues, pull requests, and
+- You have access to a
-comments on those issues and pull requests, a higher rate limit results in a
+  [GitHub Enterprise Cloud organization](https://docs.github.com/en/enterprise-cloud@latest/get-started/onboarding/getting-started-with-github-enterprise-cloud).
-faster overall import time because the GitLab importer must pause when a
+- GitLab is configured to enable [GitHub OAuth](../../../integration/github.md#enable-github-oauth-in-gitlab).
-GitHub rate limit is reached. To enable a higher rate limit for your
-self-managed or dedicated GitLab instance:
+To enable a higher rate limit:
- Ensure that you have access to a
+- [Create an OAuth app in GitHub](../../../integration/github.md#create-an-oauth-app-in-github). Ensure that the OAuth app is owned by the Enterprise Cloud Organization, not your personal GitHub account.
-  [GitHub Enterprise Cloud organization](https://docs.github.com/en/enterprise-cloud@latest/get-started/onboarding/getting-started-with-github-enterprise-cloud)
+- Perform the project import using [GitHub OAuth](#use-github-oauth).
- [Create an OAuth app in GitHub](../../../integration/github.md#create-an-oauth-app-in-github).
- Ensure that the OAuth app is owned by the Enterprise Cloud Organization, not
-  your personal GitHub account.
- [Configure GitHub OAuth in GitLab](../../../integration/github.md#enable-github-oauth-in-gitlab).
- Perform the project import using the [GitHub integration](#use-the-github-integration) and select **Authorize with GitHub** to use the OAuth authorization method.
 - Optional. By default, sign-in is enabled for all configured OAuth providers.
  If you want to enable GitHub OAuth for imports but you want to
  prevent the ability for users to sign in to your GitLab instance with GitHub,