Merge branch 'docs-aqualls-integrations-cleanup' into 'master'

Cleaning up Vale issues in integration folder

See merge request gitlab-org/gitlab!47716

doc/integration/akismet.md

@@ -6,12 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Akismet
 
-GitLab leverages [Akismet](https://akismet.com/) to protect against spam. Currently
+GitLab leverages [Akismet](https://akismet.com/) to protect against spam.
 GitLab uses Akismet to prevent the creation of spam issues on public projects. Issues
-created via the web UI or the API can be submitted to Akismet for review.
+created through the web UI or the API can be submitted to Akismet for review.
 
-Detected spam will be rejected, and an entry in the "Spam Log" section in the
-Admin page will be created.
+Detected spam is rejected, and an entry is added in the **Spam Log** section of the
+Admin page.
 
 Privacy note: GitLab submits the user's IP and user agent to Akismet.
 
@@ -23,11 +23,11 @@ In earlier GitLab versions, this only applied to API and non-project members.
 
 To use Akismet:
 
-1. Go to the URL: <https://akismet.com/account/>
-1. Sign-in or create a new account.
-1. Click on **Show** to reveal the API key.
+1. Go to the [Akismet sign-in page](https://akismet.com/account/).
+1. Sign in or create a new account.
+1. Click **Show** to reveal the API key.
 1. Go to **Admin Area > Settings > Reporting** (`/admin/application_settings/reporting`).
-1. Check the **Enable Akismet** checkbox.
+1. Select the **Enable Akismet** checkbox.
 1. Fill in the API key from step 3.
 1. Save the configuration.
 
@@ -35,23 +35,20 @@ To use Akismet:
 
 ## Training
 
-NOTE: **Note:**
-Training the Akismet filter is only available in GitLab 8.11 and later.
-
-As a way to better recognize between spam and ham, you can train the Akismet
+To better differentiate between spam and ham, you can train the Akismet
 filter whenever there is a false positive or false negative.
 
 When an entry is recognized as spam, it is rejected and added to the Spam Logs.
-From here you can review if they are really spam. If one of them is not really
+From here you can review if entries are really spam. If one of them is not really
 spam, you can use the **Submit as ham** button to tell Akismet that it falsely
 recognized an entry as spam.
 
 ![Screenshot of Spam Logs](img/spam_log.png)
 
-If an entry that is actually spam was not recognized as such, you will be able
-to also submit this to Akismet. The **Submit as spam** button will only appear
-to admin users.
+If an entry that is actually spam was not recognized as such, you can also submit
+this information to Akismet. The **Submit as spam** button is only displayed
+to administrator users.
 
 ![Screenshot of Issue](img/submit_issue.png)
 
-Training Akismet will help it to recognize spam more accurately in the future.
+Training Akismet helps it to recognize spam more accurately in the future.

doc/integration/auth0.md

@@ -12,31 +12,30 @@ application.
 1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). If you need to
    create an account, you can do so at the same link.
 
-1. Select "New App/API".
+1. Select **New App/API**.
 
 1. Provide the Application Name ('GitLab' works fine).
 
-1. Once created, you should see the Quick Start options. Disregard them and
-   select 'Settings' above the Quick Start options.
+1. After creating, you should see the **Quick Start** options. Disregard them and
+   select **Settings** above the **Quick Start** options.
 
-1. At the top of the Settings screen, you should see your Domain, Client ID and
-   Client Secret. Take note of these as you'll need to put them in the
-   configuration file. For example:
+1. At the top of the Settings screen, you should see your **Domain**, **Client ID**, and
+   **Client Secret**. These values are needed in the configuration file. For example:
    - Domain: `test1234.auth0.com`
    - Client ID: `t6X8L2465bNePWLOvt9yi41i`
    - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2`
 
-1. Fill in the Allowed Callback URLs:
+1. Fill in the **Allowed Callback URLs**:
    - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or)
    - `https://YOUR_GITLAB_URL/users/auth/auth0/callback`
 
-1. Fill in the Allowed Origins (CORS):
+1. Fill in the **Allowed Origins (CORS)**:
    - `http://YOUR_GITLAB_URL` (or)
    - `https://YOUR_GITLAB_URL`
 
 1. On your GitLab server, open the configuration file.
 
-   For Omnibus package:
+   For Omnibus GitLab:
 
    ```shell
    sudo editor /etc/gitlab/gitlab.rb
@@ -49,12 +48,12 @@ application.
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+1. Read [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
    for initial settings.
 
 1. Add the provider configuration:
 
-   For Omnibus package:
+   For Omnibus GitLab:
 
    ```ruby
    gitlab_rails['omniauth_providers'] = [
@@ -87,10 +86,14 @@ application.
 1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console
    page from step 5.
 
-1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you
-   installed GitLab via Omnibus or from source respectively.
+1. Reconfigure or restart GitLab, depending on your installation method:
 
-On the sign in page there should now be an Auth0 icon below the regular sign in
-form. Click the icon to begin the authentication process. Auth0 will ask the
-user to sign in and authorize the GitLab application. If everything goes well
-the user will be returned to GitLab and will be signed in.
+   - *If you installed from Omnibus GitLab,*
+     [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab.
+   - *If you installed from source,*
+     [restart GitLab](../administration/restart_gitlab.md#installations-from-source).
+
+On the sign-in page there should now be an Auth0 icon below the regular sign-in
+form. Click the icon to begin the authentication process. Auth0 asks the
+user to sign in and authorize the GitLab application. If the user authenticates
+successfully, the user is returned to GitLab and signed in.

doc/integration/azure.md

@@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Microsoft Azure OAuth2 OmniAuth Provider
 
-To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use.
+To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use.
 
 Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in
 the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).
@@ -15,15 +15,19 @@ As you go through the Microsoft procedure, keep the following in mind:
 
 - If you have multiple instances of Azure Active Directory, you can switch to the desired tenant.
 - You're setting up a Web application.
-- For the redirect URI, you'll need the URL of the Azure OAuth callback of your GitLab installation (for example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`). The type dropdown should be set to "Web".
+- The redirect URI requires the URL of the Azure OAuth callback of your GitLab
+  installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`.
+  The type dropdown should be set to **Web**.
 - The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation,
   the terms may be listed as `Application ID` and `Application Secret`.
-- If you need to generate a new client secret, follow the Microsoft documentation on how to [Create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret).
-- Save the client ID and client secret for your new app. Once you leave the Azure portal, you won't be able to find the client secret again.
+- If you need to generate a new client secret, follow the Microsoft documentation
+  for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret).
+- Save the client ID and client secret for your new app, as the client secret is only
+  displayed one time.
 
 1. On your GitLab server, open the configuration file.
 
-   For Omnibus package:
+   For Omnibus GitLab:
 
    ```shell
    sudo editor /etc/gitlab/gitlab.rb
@@ -37,11 +41,12 @@ As you go through the Microsoft procedure, keep the following in mind:
    sudo -u git -H editor config/gitlab.yml
    ```
 
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
+1. Refer to [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
+   for initial settings.
 
 1. Add the provider configuration:
 
-   For Omnibus package:
+   For Omnibus GitLab:
 
    ```ruby
    gitlab_rails['omniauth_providers'] = [
@@ -66,16 +71,22 @@ As you go through the Microsoft procedure, keep the following in mind:
    ```
 
    The `base_azure_url` is optional and can be added for different locales;
-   e.g. `base_azure_url: "https://login.microsoftonline.de"`.
+   such as `base_azure_url: "https://login.microsoftonline.de"`.
 
-1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above.
+1. Replace `CLIENT ID`, `CLIENT SECRET` and `TENANT ID` with the values you got above.
 
 1. Save the configuration file.
 
-1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect if you
-   installed GitLab via Omnibus or from source respectively.
+1. Reconfigure or restart GitLab, depending on your installation method:
 
-On the sign-in page, you should now see a Microsoft icon below the regular sign in form. Click the icon
-to begin the authentication process. Microsoft then asks you to sign in and authorize the GitLab application. If everything goes well, you are returned to GitLab and signed in.
-See [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user)
+   - *If you installed from Omnibus GitLab,*
+     [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab.
+   - *If you installed from source,*
+     [restart GitLab](../administration/restart_gitlab.md#installations-from-source).
+
+On the sign-in page, you should now see a Microsoft icon below the regular sign-in form.
+Click the icon to begin the authentication process. Microsoft then asks you to
+sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in.
+
+Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user)
 for information on how existing GitLab users can connect to their newly-available Azure AD accounts.

doc/integration/bitbucket.md

@@ -8,33 +8,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 NOTE: **Note:**
 Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an
-earlier version, you'll need to explicitly enable it.
-
-Import projects from Bitbucket.org and login to your GitLab instance with your
-Bitbucket.org account.
-
-## Overview
+earlier version, you must explicitly enable it.
 
 You can set up Bitbucket.org as an OAuth2 provider so that you can use your
-credentials to authenticate into GitLab or import your projects from
+Bitbucket.org account credentials to sign into GitLab or import your projects from
 Bitbucket.org.
 
-- To use Bitbucket.org as an OmniAuth provider, follow the [Bitbucket OmniAuth
-  provider](#bitbucket-omniauth-provider) section.
+- To use Bitbucket.org as an OmniAuth provider, follow the
+  [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) section.
 - To import projects from Bitbucket, follow both the
   [Bitbucket OmniAuth provider](#bitbucket-omniauth-provider) and
   [Bitbucket project import](#bitbucket-project-import) sections.
 
 ## Bitbucket OmniAuth provider
 
-NOTE: **Note:**
-GitLab 8.15 significantly simplified the way to integrate Bitbucket.org with
-GitLab. You are encouraged to upgrade your GitLab instance if you haven't done so
-already. If you're using GitLab 8.14 or below, [use the previous integration
-docs](https://gitlab.com/gitlab-org/gitlab/blob/8-14-stable-ee/doc/integration/bitbucket.md).
-
 To enable the Bitbucket OmniAuth provider you must register your application
-with Bitbucket.org. Bitbucket will generate an application ID and secret key for
+with Bitbucket.org. Bitbucket generates an application ID and secret key for
 you to use.
 
 1. Sign in to [Bitbucket.org](https://bitbucket.org).
@@ -42,26 +31,23 @@ you to use.
    settings (**Manage team**), depending on how you want the application registered.
    It does not matter if the application is registered as an individual or a
    team, that is entirely up to you.
-1. Select **OAuth** in the left menu under "Access Management".
+1. In the left menu under **Access Management**, select **OAuth**.
 1. Select **Add consumer**.
 1. Provide the required details:
 
-   | Item | Description |
-   | :--- | :---------- |
-   | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. |
-   | **Application description** | Fill this in if you wish. |
-   | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. |
-   | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. |
-
-   NOTE: Be sure to append `/users/auth` to the end of the callback URL
-   to prevent a [OAuth2 convert
-   redirect](http://tetraph.com/covert_redirect/) vulnerability.
-
-   NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will
-   see an "Invalid redirect_uri" message. For more details, see [the
-   Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html).
+   - **Name:** This can be anything. Consider something like `<Organization>'s GitLab`
+     or `<Your Name>'s GitLab` or something else descriptive.
+   - **Application description:** *(Optional)* Fill this in if you wish.
+   - **Callback URL:** (Required in GitLab versions 8.15 and greater)
+     The URL to your GitLab installation, such as
+     `https://gitlab.example.com/users/auth`. Be sure to append `/users/auth` to
+     the end of the callback URL to prevent an
+     [OAuth2 convert redirect](http://tetraph.com/covert_redirect/) vulnerability.
+     Leaving this field empty
+     [results in an `Invalid redirect_uri` message](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html).
+   - **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`.
 
-   And grant at least the following permissions:
+1. Grant at least the following permissions:
 
    ```plaintext
    Account: Email, Read
@@ -75,8 +61,8 @@ you to use.
    ![Bitbucket OAuth settings page](img/bitbucket_oauth_settings_page.png)
 
 1. Select **Save**.
-1. Select your newly created OAuth consumer and you should now see a Key and
-   Secret in the list of OAuth consumers. Keep this page open as you continue
+1. Select your newly created OAuth consumer, and you should now see a **Key** and
+   **Secret** in the list of OAuth consumers. Keep this page open as you continue
    the configuration.
 
    ![Bitbucket OAuth key](img/bitbucket_oauth_keys.png)
@@ -125,16 +111,16 @@ you to use.
 
 1. Save the configuration file.
 1. For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed via
-   Omnibus, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source.
+   Omnibus GitLab, or [restart](../administration/restart_gitlab.md#installations-from-source) if installed from source.
 
-On the sign in page there should now be a Bitbucket icon below the regular sign
-in form. Click the icon to begin the authentication process. Bitbucket will ask
-the user to sign in and authorize the GitLab application. If everything goes
-well, the user will be returned to GitLab and will be signed in.
+On the sign-in page there should now be a Bitbucket icon below the regular
+sign-in form. Click the icon to begin the authentication process. Bitbucket asks
+the user to sign in and authorize the GitLab application. If successful, the user
+is returned to GitLab and signed in.
 
 ## Bitbucket project import
 
-Once the above configuration is set up, you can use Bitbucket to sign into
+After the above configuration is set up, you can use Bitbucket to sign into
 GitLab and [start importing your projects](../user/project/import/bitbucket.md).
 
 If you want to import projects from Bitbucket, but don't want to enable signing in,