Manage secret scanning push bypasses at the organization level [Publi…

…c Beta] #15792 (#52250)

Co-authored-by: Joe Clark <[email protected]>

content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection.md

@@ -18,42 +18,68 @@ shortTitle: Manage bypass requests
 
 {% data reusables.secret-scanning.push-protection-delegate-bypass-beta-note %}
 
-{% data reusables.secret-scanning.push-protection-delegated-bypass-intro %}
+When enabling delegated bypass for push protection, organization owners or repository administrators decide which {% ifversion push-protection-bypass-fine-grained-permissions %}individuals, {% endif %}roles or teams can review (approve or deny) requests to bypass push protection.
 
-An organization owner or repository administrator defines which roles and teams are included in a bypass list. Members of the bypass list can view and manage all requests for bypass privileges on the "Push protection bypass" page, located under the **Security** tab of the repository. For more information, see "[AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection)."
+When a contributor requests bypass privileges to push a commit containing a secret, this designated group of reviewers:
 
-{% data reusables.secret-scanning.push-protection-delegated-bypass-note %}
+* Receives an email notification containing a link to the request.
+* Reviews the request in the "Bypass requests" page of the repository{% ifversion security-overview-delegated-bypass-requests %}, or in the organization's security overview{% endif %}.
+* Has 7 days to either approve or deny the request before the request expires.
 
-To help you effectively triage secrets for which there is a bypass request, {% data variables.product.prodname_dotcom %} displays the following information in the request:
+To help reviewers efficiently triage secrets for which there is a bypass request, {% data variables.product.prodname_dotcom %} displays the following information in the request:
 
 * Name of the user who attempted the push.
 * Repository where the push was attempted.
 * Commit hash of the push.
 * Timestamp of the push.{% ifversion push-protection-delegated-bypass-enhancements %}
 * File path and branch information. The branch information is only available for pushes to single branches.{% endif %}
 
-### Managing requests to bypass push protection at the repository level
+The contributor is notified of the decision by email and must take the required action:
+
+* If the request is approved, the contributor can push the commit containing the secret to the repository.
+* If the request is denied, the contributor must remove the secret from the commit in order to successfully push the commit to the repository.
+
+### Managing requests for a repository
 
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-security %}
 {% data reusables.repositories.bypass-requests-settings %}
-1. Select the **All statuses** dropdown menu, then click **Open** to view requests that are awaiting review, or that have been approved but for which the commits haven't been pushed to the repository yet.
+1. Select the **All statuses** dropdown menu, then click **Open** to view requests that are awaiting review, and those that have been approved but for which the commits haven't been pushed to the repository yet.
 1. Click the request that you want to review.
 1. Review the details of the request.
 1. To allow the contributor to push the commit containing the secret, click **Approve bypass request**. Or, to require the contributor to remove the secret from the commit, click **Deny bypass request**.
 
-### Filtering by request status
+{% ifversion security-overview-delegated-bypass-requests %}
+
+### Managing requests for an organization
+
+Organization owners, security managers and organization members with the relevant fine-grained permission (via a custom role) can review and manage bypass requests for all repositories in the organization using security overview. See "[AUTOTITLE](/code-security/security-overview/reviewing-requests-to-bypass-push-protection)."
+
+{% endif %}
+
+### Filtering requests
+
+You can filter requests by:
+
+* Approver (member of the bypass list)
+* Requester (contributor making the request)
+* Timeframe
+* Status
+
+#### Filtering by status
 
-You can filter requests by approver (member of the bypass list), requester (contributor making the request), timeframe, and status. The following statuses are assigned to a request:
+The following statuses are assigned to a request:
 
 |Status|Description|
 |---------|-----------|
-|`Cancelled`| The request has been cancelled by the contributor.|
+|`Cancelled`| The request has been canceled by the contributor.|
 |`Completed`|The request has been approved and the commit(s) have been pushed to the repository.|
 |`Denied`|The request has been reviewed and denied.|
 |`Expired`| The request has expired. Requests are valid for 7 days. |
 |`Open`| The request has either not yet been reviewed, or has been approved but the commit(s) have not been pushed to the repository.  |
 
-When a contributor requests bypass privileges to push a commit containing a secret, members of the bypass list all receive an email notification containing a link to the request. Members of the bypass list then have 7 days to review and either approve or deny the request before the request expires.
+## Further reading
 
-The contributor is notified of the decision by email and must take the required action. If the request is approved, the contributor can push the commit containing the secret to the repository. If the request is denied, the contributor must remove the secret from the commit in order to successfully push the commit to the repository.
+* "[AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection)"
+* "[AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection)"{% ifversion security-overview-delegated-bypass-requests %}
+* "[AUTOTITLE](/code-security/security-overview/reviewing-requests-to-bypass-push-protection)"{% endif %}

content/code-security/security-overview/index.md

@@ -21,4 +21,5 @@ children:
   - /exporting-data-from-security-overview
   - /viewing-metrics-for-secret-scanning-push-protection
   - /viewing-metrics-for-pull-request-alerts
+  - /reviewing-requests-to-bypass-push-protection
 ---

content/code-security/security-overview/reviewing-requests-to-bypass-push-protection.md

@@ -0,0 +1,56 @@
+---
+title: Reviewing requests to bypass push protection
+shortTitle: Review bypass requests
+intro: 'You can use security overview to review requests to bypass push protection from contributors pushing to repositories across your organization.'
+permissions: '{% data reusables.security-overview.permissions %}'
+product: '{% data reusables.gated-features.security-overview %}'
+type: how_to
+topics:
+  - Security overview
+  - Advanced Security
+  - Organizations
+  - Teams
+  - Secret scanning
+  - Alerts
+versions:
+  feature: security-overview-delegated-bypass-requests
+---
+
+## About bypass requests
+
+If your organization has configured delegated bypass for push protection, a designated team of reviewers controls which organization members can push secrets to repositories in your organization, and which members must first make a "bypass request" in order to push the secret.
+
+On the "Bypass requests" page in security overview, reviewers can find, review (approve or deny) and manage these requests.
+
+For more information, see "[AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection)."
+
+## Reviewing bypass requests for an organization
+
+{% data reusables.organizations.navigate-to-org %}
+{% data reusables.organizations.security-overview %}
+1. In the sidebar, under "Requests", click **{% octicon "key" aria-hidden="true"  %} Push protection bypass**.
+1. Select the **All statuses** dropdown menu, then click **Open** to view requests that are awaiting review, or that have been approved but for which the commits haven't been pushed to the repository yet.
+1. Click the request that you want to review.
+1. Review the details of the request.
+1. To allow the contributor to push the commit containing the secret, click **Approve bypass request**. Or, to require the contributor to remove the secret from the commit, click **Deny bypass request**.
+
+## Filtering requests
+
+You can filter requests by repository, approver (member who has reviewed the request), requester (contributor making the request), timeframe, and status.
+
+### Filtering by status
+
+The following statuses are assigned to a request:
+
+|Status|Description|
+|---------|-----------|
+|`Cancelled`| The request has been cancelled by the contributor.|
+|`Completed`|The request has been approved and the commit(s) have been pushed to the repository.|
+|`Denied`|The request has been reviewed and denied.|
+|`Expired`| The request has expired. Requests are valid for 7 days. |
+|`Open`| The request has either not yet been reviewed, or has been approved but the commit(s) have not been pushed to the repository.  |
+
+## Further reading
+
+* "[AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection)"
+* "[AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection)"

data/features/security-overview-delegated-bypass-requests.yml

@@ -0,0 +1,5 @@
+# Reference: #15792
+# Documentation for the bypass requests page for delegated bypass at the org-level (security overview)
+versions:
+  ghec: '*'
+  ghes: '>3.15'

data/reusables/secret-scanning/push-protection-delegated-bypass-note.md

@@ -1 +1,6 @@
-Members {% ifversion push-protection-bypass-fine-grained-permissions %}with permission to review and manage bypass requests {% else %}of the bypass list{% endif %} are still protected from accidentally pushing secrets to a repository. If they attempt to push a commit containing a secret, their push is still blocked, but they can choose to bypass the block by specifying a reason for allowing the push. Members {% ifversion push-protection-bypass-fine-grained-permissions %}with permission to review and manage bypass requests {% else %}of the bypass list {% endif %}do not have to request bypass privileges from other members in order to override the block.
+Members {% ifversion push-protection-bypass-fine-grained-permissions %}with permission to review and manage bypass requests {% else %}of the bypass list{% endif %} are still protected from accidentally pushing secrets to a repository. If they attempt to push a commit containing a secret, their push is still blocked, but they can choose to bypass the block by specifying a reason for allowing the push. The following types of people can bypass push protection without requesting bypass privileges:
+
+* Organization owners
+* Security managers
+* Users in teams, default roles, or custom roles that have been added to the bypass list.{% ifversion push-protection-bypass-fine-grained-permissions %}
+* Users who are assigned (either directly or via a team) a custom role with the "review and manage secret scanning bypass requests" fine-grained permission.{% endif %}