[2022-07-27]: Secret scanning: Email on bypass - [GA] (#29233)

content/code-security/secret-scanning/protecting-pushes-with-secret-scanning.md

@@ -24,6 +24,12 @@ shortTitle: Push protection
 
 Up to now, {% data variables.product.prodname_secret_scanning_GHAS %} checks for secrets _after_ a push and alerts users to exposed secrets. {% data reusables.secret-scanning.push-protection-overview %}
 
+If a contributor bypasses a push protection block for a secret, {% data variables.product.prodname_dotcom %}:
+- generates an alert.
+- creates an alert in the "Security" tab of the repository.
+- adds the bypass event to the audit log.{% ifversion secret-scanning-push-protection-email %}
+- sends an email alert to organization owners, security managers, and repository administrators, with a link to the related secret and the reason why it was allowed.{% endif %}
+
 {% data variables.product.prodname_secret_scanning_caps %} as a push protection currently scans repositories for secrets issued by the following service providers.
 
 {% data reusables.secret-scanning.secret-list-private-push-protection %}
@@ -78,6 +84,8 @@ If you confirm a secret is real and that you intend to fix it later, you should
 
 {% data reusables.secret-scanning.push-protection-allow-secrets-alerts %}
 
+{% data reusables.secret-scanning.push-protection-allow-email %}
+
 1. Visit the URL returned by {% data variables.product.prodname_dotcom %} when your push was blocked.
   ![Screenshot showing form with options for unblocking the push of a secret](/assets/images/help/repository/secret-scanning-unblock-form.png)
 {% data reusables.secret-scanning.push-protection-choose-allow-secret-options %}
@@ -103,6 +111,8 @@ If {% data variables.product.prodname_dotcom %} blocks a secret that you believe
 
 {% data reusables.secret-scanning.push-protection-allow-secrets-alerts %}
 
+{% data reusables.secret-scanning.push-protection-allow-email %}
+
 If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible.
 
 1. In the banner that appeared at the top of the page when {% data variables.product.prodname_dotcom %} blocked your commit, click **Bypass protection**.

data/features/secret-scanning-push-protection-email.yml

@@ -0,0 +1,6 @@
+# Reference: #7511.
+# When developers bypass a block by push protection for a detected secret, administrators will receive an email notification of that bypass.
+versions:
+  ghec: '*'
+  ghes: '>=3.7'
+  ghae: 'issue-7511'

data/reusables/secret-scanning/push-protection-allow-email.md

@@ -0,0 +1,3 @@
+{% ifversion secret-scanning-push-protection-email %}
+When a contributor bypasses a push protection block for a secret, {% data variables.product.prodname_dotcom %} also sends an email alert to the organization owners, security managers, and repository administrators who have opted in for email notifications.
+{% endif %}