Merge branch '258980-feature-flag-rollout-of-admin-approval-for-new-user-signups' into 'master'

Add docs for: `Optional admin approval for local user sign up` feature

See merge request gitlab-org/gitlab!44963

app/views/admin/application_settings/_signup.html.haml

@@ -16,7 +16,7 @@
           = f.label :require_admin_approval_after_user_signup, class: 'form-check-label' do
             = _('Require admin approval for new sign-ups')
             .form-text.text-muted
-              = _("When enabled, any user visiting %{host} and creating an account will have to be explicitly approved by the admin before they can login. This setting is effective only if sign-ups are enabled.") % { host: "#{new_user_session_url(host: Gitlab.config.gitlab.host)}" }
+              = _("When enabled, any user visiting %{host} and creating an account will have to be explicitly approved by an admin before they can sign in. This setting is effective only if sign-ups are enabled.") % { host: "#{new_user_session_url(host: Gitlab.config.gitlab.host)}" }
     .form-group
       .form-check
         = f.check_box :send_user_confirmation_email, class: 'form-check-input'

config/locales/devise.en.yml

@@ -45,7 +45,7 @@ en:
       signed_up_but_inactive: "You have signed up successfully. However, we could not sign you in because your account is not yet activated."
       signed_up_but_locked: "You have signed up successfully. However, we could not sign you in because your account is locked."
       signed_up_but_unconfirmed: "A message with a confirmation link has been sent to your email address. Please follow the link to activate your account."
-      signed_up_but_blocked_pending_approval: "You have signed up successfully. However, we could not sign you in because your account is awaiting approval from your administrator."
+      signed_up_but_blocked_pending_approval: "You have signed up successfully. However, we could not sign you in because your account is awaiting approval from your GitLab administrator."
       update_needs_confirmation: "You updated your account successfully, but we need to verify your new email address. Please check your email and follow the confirm link to confirm your new email address."
       updated: "Your account has been updated successfully."
     sessions:

doc/subscriptions/self_managed/index.md

@@ -25,7 +25,7 @@ using [Seat Link](#seat-link).
 
 Every occupied seat is counted in the subscription, with the following exceptions:
 
-- [Deactivated](../../user/admin_area/activating_deactivating_users.md#deactivating-a-user) and
+- [Deactivated](../../user/admin_area/activating_deactivating_users.md#deactivating-a-user), [pending approval](../../user/admin_area/approving_users.md) and
   [blocked](../../user/admin_area/blocking_unblocking_users.md) users who are restricted prior to the
   renewal of a subscription won't be counted as active users for the renewal subscription. They may
   count as active users in the subscription period in which they were originally added.

doc/user/admin_area/approving_users.md

+---
+stage: Manage
+group: Access
+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/#designated-technical-writers
+type: howto
+---
+
+# Users pending approval
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5.
+
+When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-admin-approval-for-new-sign-ups) is enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state.
+
+A user pending approval is functionally identical to a [blocked](blocking_unblocking_users.md) user. 
+
+A user pending approval:
+
+- Will not be able to sign in.
+- Cannot access Git repositories or the API.
+- Will not receive any notifications from GitLab.
+- Does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users).
+
+## Approving a user
+
+A user that is pending approval can be approved from the Admin Area. To do this:
+
+1. Navigate to  **Admin Area > Overview > Users**.
+1. Click on the **Pending approval** tab.
+1. Select a user.
+1. Under the **Account** tab, click **Approve user**.
+
+Approving a user:
+
+1. Activates their account.
+1. Changes the user's state to active and it consumes a
+[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users).

doc/user/admin_area/settings/sign_up_restrictions.md

@@ -7,6 +7,7 @@ type: reference
 You can use sign-up restrictions to:
 
 - Disable new sign-ups.
+- Require admin approval for new sign-ups.
 - Require user email confirmation.
 - Denylist or allowlist email addresses belonging to specific domains.
 
@@ -32,12 +33,20 @@ Alternatively, you could also consider setting up a
 [allowlist](#allowlist-email-domains) or [denylist](#denylist-email-domains) on
 email domains to prevent malicious users from creating accounts.
 
+## Require admin approval for new sign-ups
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5.
+
+When this setting is enabled, any user visiting your GitLab domain and signing up for a new account will have to be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account.
+
+![Require admin approval for new signups](img/sign_up_restrictions_v13_5.png)
+
 ## Require email confirmation
 
 You can send confirmation emails during sign-up and require that users confirm
 their email address before they are allowed to sign in.
 
-![Email confirmation](img/email_confirmation_v12_7.png)
+![Email confirmation](img/sign_up_restrictions_v13_5.png)
 
 ## Minimum password length limit
 

locale/gitlab.pot

@@ -29453,7 +29453,7 @@ msgstr ""
 msgid "When a runner is locked, it cannot be assigned to other projects"
 msgstr ""
 
-msgid "When enabled, any user visiting %{host} and creating an account will have to be explicitly approved by the admin before they can login. This setting is effective only if sign-ups are enabled."
+msgid "When enabled, any user visiting %{host} and creating an account will have to be explicitly approved by an admin before they can sign in. This setting is effective only if sign-ups are enabled."
 msgstr ""
 
 msgid "When enabled, any user visiting %{host} will be able to create an account."

spec/controllers/registrations_controller_spec.rb

@@ -75,7 +75,7 @@ RSpec.describe RegistrationsController do
 
             expect(response).to redirect_to(new_user_session_path(anchor: 'login-pane'))
             expect(flash[:notice])
-              .to eq('You have signed up successfully. However, we could not sign you in because your account is awaiting approval from your administrator.')
+              .to eq('You have signed up successfully. However, we could not sign you in because your account is awaiting approval from your GitLab administrator.')
           end
 
           context 'email confirmation' do