Merge branch 'russell/improve-sign-up-restrictions-docs' into 'master'

Improve sign-up restrictions docs

See merge request gitlab-org/gitlab!53682

doc/user/admin_area/approving_users.md

@@ -7,30 +7,49 @@ type: howto
 
 # Users pending approval
 
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5.
+A user in _pending approval_ state requires action by an administrator. A user sign up can be in a
+pending approval state because an administrator has enabled either, or both, of the following
+options:
 
-When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-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.
+- [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting.
+- [User cap](settings/sign_up_restrictions.md#user-cap).
 
-A user pending approval is functionally identical to a [blocked](blocking_unblocking_users.md) user.
+When a user registers for an account while this setting is enabled:
+
+- The user is placed in a **Pending approval** state.
+- The user sees a message telling them their account is awaiting approval by an administrator.
 
 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.
+- Is functionally identical to a [blocked](blocking_unblocking_users.md) user.
+- Cannot sign in.
+- Cannot access Git repositories or the GitLab API.
+- Does not receive any notifications from GitLab.
 - Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users).
 
-## Approving a user
+An administrator must [approve their sign up](#approve-or-reject-a-user-sign-up) to allow them to
+sign in.
+
+## View user sign ups pending approval
+
+To view user sign ups pending approval:
+
+1. Go to **Admin Area > Overview > Users**.
+1. Select the **Pending approval** tab.
+
+## Approve or reject a user sign up
+
+A user sign up pending approval can be approved or rejected from the Admin Area.
 
-A user that is pending approval can be approved from the Admin Area. To do this:
+To approve or reject a user sign up:
 
-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**.
+1. Go to  **Admin Area > Overview > Users**.
+1. Select the **Pending approval** tab.
+1. In the user's row select settings (**{settings}**).
+1. Select **Approve** or **Reject**.
 
 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#billable-users).
+- Activates their account.
+- Changes the user's state to active.
+- Consumes a subscription [seat](../../subscriptions/self_managed/index.md#billable-users).

doc/user/admin_area/settings/sign_up_restrictions.md

@@ -30,7 +30,7 @@ To disable sign ups:
 > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5.
 > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6.
 
-When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account. This setting is enabled by default for newly created instances. This setting is only applicable if sign ups are enabled.
+When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using their account. In GitLab 13.6 and later, this setting is enabled by default for new GitLab instances. It is only applicable if sign ups are enabled.
 
 To require administrator approval for new sign ups:
 
@@ -56,10 +56,48 @@ To enforce confirmation of the email address used for new sign ups:
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9.
 
 When the number of billable users reaches the user cap, any user who is added or requests access must be
-[approved](../approving_users.md#approving-a-user) by an administrator before they can start using
+[approved](../approving_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using
 their account.
 
-If an administrator increases or removes the user cap, the users in pending approval state are
+If an administrator [increases](#set-the-user-cap-number) or [removes](#remove-the-user-cap) the
+user cap, the users in pending approval state are automatically approved in a background job.
+
+### Enable or disable User cap **(FREE SELF)**
+
+User cap is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can opt to disable it.
+
+To disable it:
+
+```ruby
+Feature.disable(:admin_new_user_signups_cap)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:admin_new_user_signups_cap)
+```
+
+### Set the user cap number
+
+1. Go to  **Admin Area > Settings > General**.
+1. Expand **Sign-up restrictions**.
+1. Enter a number in **User cap**.
+1. Select **Save changes**.
+
+New user sign ups are subject to the user cap restriction.
+
+## Remove the user cap
+
+1. Go to  **Admin Area > Settings > General**.
+1. Expand **Sign-up restrictions**.
+1. Remove the number from **User cap**.
+1. Select **Save changes**.
+
+New users sign ups are not subject to the user cap restriction. Users in pending approval state are
 automatically approved in a background job.
 
 ## Soft email confirmation