Merge branch 'kpaizee-github-ctrt-edits' into 'master'

CTRT edits for GitHub page - part 1

See merge request gitlab-org/gitlab!80073

doc/administration/get_started.md

@@ -62,7 +62,7 @@ You may need to import projects from external sources like GitHub, Bitbucket, or
 
 ### Popular project imports
 
-- [GitHub Enterprise to self-managed GitLab](../integration/github.md#enabling-github-oauth): Enabling OAuth makes it easier for developers to find and import their projects.
+- [GitHub Enterprise to self-managed GitLab](../integration/github.md): Enabling OAuth makes it easier for developers to find and import their projects.
 - [Bitbucket Server](../user/project/import/bitbucket_server.md#limitations): There are certain data limitations.
   For assistance with these data types, contact your GitLab account manager or GitLab Support about our professional migration services.
 

doc/ci/ci_cd_for_external_repos/github_integration.md

@@ -16,7 +16,7 @@ Watch a video on [Using GitLab CI/CD pipelines with GitHub repositories](https:/
 
 NOTE:
 Because of [GitHub limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/9147),
-[GitHub OAuth](../../integration/github.md#enabling-github-oauth)
+[GitHub OAuth](../../integration/github.md#enable-github-oauth-in-gitlab)
 cannot be used to authenticate with GitHub as an external CI/CD repository.
 
 ## Connect with Personal Access Token

doc/integration/github.md

@@ -4,116 +4,117 @@ group: Integrations
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Integrate your GitLab instance with GitHub **(FREE SELF)**
+# Use GitHub as an authentication provider **(FREE SELF)**
 
-You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. This integration
-enables users to import projects from GitHub, or sign in to your GitLab instance
-with their GitHub account.
+You can integrate your GitLab instance with GitHub.com and GitHub Enterprise.
+You can import projects from GitHub, or sign in to GitLab
+with your GitHub credentials.
 
-## Security check
+## Create an OAuth app in GitHub
 
-Some integrations risk compromising GitLab accounts. To help mitigate this
-[OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/)
-vulnerability, append `/users/auth` to the end of the authorization callback URL.
+To enable the GitHub OmniAuth provider, you need an OAuth 2.0 client ID and client
+secret from GitHub:
 
-However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`.
-This means that a subdomain takeover, an XSS, or an open redirect on any subdomain of
-your website could enable the covert redirect attack.
-
-## Enabling GitHub OAuth
-
-To enable the GitHub OmniAuth provider, you need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app).
-
-When you create an OAuth 2 app in GitHub, you need the following information:
-
-- The URL of your GitLab instance, such as `https://gitlab.example.com`.
-- The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port.
+1. Sign in to GitHub.
+1. [Create an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)
+   and provide the following information:
+   - The URL of your GitLab instance, such as `https://gitlab.example.com`.
+   - The authorization callback URL, such as, `https://gitlab.example.com/users/auth`.
+     Include the port number if your GitLab instance uses a non-default port.
 
-See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
+### Check for security vulnerabilities
 
-After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps.
+For some integrations, the [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/)
+vulnerability can compromise GitLab accounts.
+To mitigate this vulnerability, append `/users/auth` to the authorization
+callback URL.
 
-| Setting from GitHub  | Substitute in the GitLab configuration file  | Description |
-|:---------------------|:---------------------------------------------|:------------|
-| Client ID            | `YOUR_APP_ID`                                | OAuth 2 Client ID |
-| Client Secret        | `YOUR_APP_SECRET`                            | OAuth 2 Client Secret |
-| URL                  | `https://github.example.com/`                | GitHub Deployment URL |
+However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`.
+Therefore, a subdomain takeover, an XSS, or an open redirect on any subdomain of
+your website could enable the covert redirect attack.
 
-Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
+## Enable GitHub OAuth in GitLab
 
-**For Omnibus installations**
+1. [Configure the initial settings](omniauth.md#configure-initial-settings) in GitLab.
 
-1. Edit `/etc/gitlab/gitlab.rb`:
+1. Edit the GitLab configuration file using the following information:
 
-   For GitHub.com:
+   | GitHub setting | Value in the GitLab configuration file | Description             |
+   |----------------|----------------------------------------|-------------------------|
+   | Client ID      | `YOUR_APP_ID`                          | OAuth 2.0 client ID     |
+   | Client secret  | `YOUR_APP_SECRET`                      | OAuth 2.0 client secret |
+   | URL            | `https://github.example.com/`          | GitHub deployment URL   |
 
-   ```ruby
-   gitlab_rails['omniauth_providers'] = [
-     {
-       name: "github",
-       # label: "Provider name", # optional label for login button, defaults to "GitHub"
-       app_id: "YOUR_APP_ID",
-       app_secret: "YOUR_APP_SECRET",
-       args: { scope: "user:email" }
-     }
-   ]
-   ```
+   - **For Omnibus installations**
 
-   For GitHub Enterprise:
+     1. Open the `/etc/gitlab/gitlab.rb` file.
 
-   ```ruby
-   gitlab_rails['omniauth_providers'] = [
-     {
-       name: "github",
-       # label: "Provider name", # optional label for login button, defaults to "GitHub"
-       app_id: "YOUR_APP_ID",
-       app_secret: "YOUR_APP_SECRET",
-       url: "https://github.example.com/",
-       args: { scope: "user:email" }
-     }
-   ]
-   ```
+        For GitHub.com, update the following section:
 
-   **Replace `https://github.example.com/` with your GitHub URL.**
+        ```ruby
+        gitlab_rails['omniauth_providers'] = [
+          {
+            name: "github",
+            # label: "Provider name", # optional label for login button, defaults to "GitHub"
+            app_id: "YOUR_APP_ID",
+            app_secret: "YOUR_APP_SECRET",
+            args: { scope: "user:email" }
+          }
+        ]
+        ```
 
-1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect.
+        For GitHub Enterprise, update the following section and replace
+        `https://github.example.com/` with your GitHub URL:
 
----
+        ```ruby
+        gitlab_rails['omniauth_providers'] = [
+          {
+            name: "github",
+            # label: "Provider name", # optional label for login button, defaults to "GitHub"
+            app_id: "YOUR_APP_ID",
+            app_secret: "YOUR_APP_SECRET",
+            url: "https://github.example.com/",
+            args: { scope: "user:email" }
+          }
+        ]
+        ```
 
-**For installations from source**
+     1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
+        GitLab.
 
-1. Navigate to your repository and edit `config/gitlab.yml`:
+   - **For installations from source**
 
-   For GitHub.com:
+     1. Open the `config/gitlab.yml` file.
 
-   ```yaml
-   - { name: 'github',
-       # label: 'Provider name', # optional label for login button, defaults to "GitHub"
-       app_id: 'YOUR_APP_ID',
-       app_secret: 'YOUR_APP_SECRET',
-       args: { scope: 'user:email' } }
-   ```
+        For GitHub.com, update the following section:
 
-   For GitHub Enterprise:
+        ```yaml
+        - { name: 'github',
+            # label: 'Provider name', # optional label for login button, defaults to "GitHub"
+            app_id: 'YOUR_APP_ID',
+            app_secret: 'YOUR_APP_SECRET',
+            args: { scope: 'user:email' } }
+        ```
 
-   ```yaml
-   - { name: 'github',
-       # label: 'Provider name', # optional label for login button, defaults to "GitHub"
-       app_id: 'YOUR_APP_ID',
-       app_secret: 'YOUR_APP_SECRET',
-       url: "https://github.example.com/",
-       args: { scope: 'user:email' } }
-   ```
+        For GitHub Enterprise, update the following section and replace
+        `https://github.example.com/` with your GitHub URL:
 
-   **Replace `https://github.example.com/` with your GitHub URL.**
+        ```yaml
+        - { name: 'github',
+            # label: 'Provider name', # optional label for login button, defaults to "GitHub"
+            app_id: 'YOUR_APP_ID',
+            app_secret: 'YOUR_APP_SECRET',
+            url: "https://github.example.com/",
+            args: { scope: 'user:email' } }
+        ```
 
-1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect.
-
----
+     1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
+        GitLab.
 
-1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form.
+1. Refresh the GitLab sign-in page. A GitHub icon should display below the
+   sign-in form.
 
-1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application.
+1. Select the icon. Sign in to GitHub and authorize the GitLab application.
 
 ## GitHub Enterprise with self-signed Certificate