repo sync

content/code-security/secret-scanning/about-secret-scanning.md

@@ -38,6 +38,13 @@ If your project communicates with an external service, you might use a token or
 
 Service providers can partner with {% data variables.product.company_short %} to provide their secret formats for scanning. {% data reusables.secret-scanning.partner-program-link %}
 
+{% if secret-scanning-push-protection %}
+
+You can also enable {% data variables.product.prodname_secret_scanning %} as a push protection for a repository or an organization. When you enable this feature, {% data variables.product.prodname_secret_scanning %} prevents contributors from pushing code with a detected secret. To proceed, contributors must either remove the secret(s) from the push or, if needed, bypass the protection. For more information, see "[Protecting pushes with {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)."
+
+{% endif %}
+
+
 {% ifversion fpt or ghec %}
 ## About {% data variables.product.prodname_secret_scanning_partner %}
 

content/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories.md

@@ -35,7 +35,10 @@ You can enable {% data variables.product.prodname_secret_scanning_GHAS %} for an
 5. Review the impact of enabling {% data variables.product.prodname_advanced_security %}, then click **Enable {% data variables.product.prodname_GH_advanced_security %} for this repository**.
 6. When you enable {% data variables.product.prodname_advanced_security %}, {% data variables.product.prodname_secret_scanning %} may automatically be enabled for the repository due to the organization's settings. If "{% data variables.product.prodname_secret_scanning_caps %}" is shown with an **Enable** button, you still need to enable {% data variables.product.prodname_secret_scanning %} by clicking **Enable**. If you see a **Disable** button, {% data variables.product.prodname_secret_scanning %} is already enabled. 
    ![Enable {% data variables.product.prodname_secret_scanning %} for your repository](/assets/images/help/repository/enable-secret-scanning-dotcom.png)
-
+{% if secret-scanning-push-protection %}
+7. Optionally, if you want to enable push protection, click **Enable** to the right of "Push protection." {% data reusables.secret-scanning.push-protection-overview %} For more information, see "[Protecting pushes with {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)."
+   ![Enable push protection for your repository](/assets/images/help/repository/secret-scanning-enable-push-protection.png)
+{% endif %}
 {% ifversion ghae %}
 1. Before you can enable {% data variables.product.prodname_secret_scanning %}, you need to enable {% data variables.product.prodname_GH_advanced_security %} first. To the right of "{% data variables.product.prodname_GH_advanced_security %}", click **Enable**.
    ![Enable {% data variables.product.prodname_GH_advanced_security %} for your repository](/assets/images/enterprise/github-ae/repository/enable-ghas-ghae.png)

content/code-security/secret-scanning/index.md

@@ -20,5 +20,6 @@ children:
   - /defining-custom-patterns-for-secret-scanning
   - /managing-alerts-from-secret-scanning
   - /secret-scanning-patterns
+  - /protecting-pushes-with-secret-scanning
 ---
 

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

@@ -0,0 +1,88 @@
+---
+title: Protecting pushes with secret scanning
+intro: 'You can use {% data variables.product.prodname_secret_scanning %} to prevent supported secrets from being pushed into your organization or repository by enabling push protection.'
+product: '{% data reusables.gated-features.secret-scanning %}'
+miniTocMaxHeadingLevel: 3
+versions:
+  feature: 'secret-scanning-push-protection'
+redirect_from:
+  - /early-access/code-security/secret-scanning/protecting-pushes-with-secret-scanning
+type: how_to
+topics:
+  - Secret scanning
+  - Advanced Security
+  - Alerts
+  - Repositories
+shortTitle: Push protection
+---
+
+{% data reusables.secret-scanning.beta %}
+{% data reusables.secret-scanning.enterprise-enable-secret-scanning %}
+{% data reusables.secret-scanning.push-protection-beta %}
+
+## About push protection for secrets
+
+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 %}
+
+{% 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 %}
+
+## Enabling {% data variables.product.prodname_secret_scanning %} as a push protection
+
+For you to use {% data variables.product.prodname_secret_scanning %} as a push protection, the organization or repository needs to have both {% data variables.product.prodname_GH_advanced_security %} and {% data variables.product.prodname_secret_scanning %} enabled. For more information, see "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)," "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)," and "[About {% data variables.product.prodname_GH_advanced_security %}](/get-started/learning-about-github/about-github-advanced-security)."
+
+Organization owners, security managers, and repository administrators can enable push protection for {% data variables.product.prodname_secret_scanning %} via the UI and API. For more information, see "[Repositories](/rest/reference/repos#update-a-repository)" and expand the "Properties of the `security_and_analysis` object" section in the REST API documentation.
+
+### Enabling {% data variables.product.prodname_secret_scanning %} as a push protection for an organization
+
+{% data reusables.organizations.navigate-to-org %}
+{% data reusables.organizations.org_settings %}
+{% data reusables.organizations.security-and-analysis %}
+{% data reusables.repositories.navigate-to-ghas-settings %}
+{% data reusables.advanced-security.secret-scanning-push-protection-org %}
+
+### Enabling {% data variables.product.prodname_secret_scanning %} as a push protection for a repository
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.navigate-to-security-and-analysis %}
+{% data reusables.repositories.navigate-to-ghas-settings %}
+{% data reusables.advanced-security.secret-scanning-push-protection-repo %}
+
+
+## Using {% data variables.product.prodname_secret_scanning %} as a push protection from the command line
+
+When you attempt to push a supported secret to a repository or organization with {% data variables.product.prodname_secret_scanning %} as a push protection enabled, {% data variables.product.prodname_dotcom %} will block the push. You can remove the secret from your commit or follow a provided URL to allow the push.
+
+Up to five detected secrets will be displayed at a time on the command line. If a particular secret has already been detected in the repository and an alert already exists, {% data variables.product.prodname_dotcom %} will not block that secret. 
+
+![Screenshot showing that a push is blocked when a user attempts to push a secret to a repository](/assets/images/help/repository/secret-scanning-push-protection-with-link.png)
+
+If you need to remove the secret from your latest commit (that is, `HEAD`) on the branch being pushed and any earlier commits that contain the secret, you can remove the secret from `HEAD`, then squash the commits between when the commit was introduced and the first version of `HEAD` for which the secret has been removed.
+
+{% note %}
+
+**Notes**: 
+
+* If your git configuration supports pushes to multiple branches, and not only to the default branch, your push may be blocked due to additional and unintended refs being pushed. For more information, see the [`push.default` options](https://git-scm.com/docs/git-config#Documentation/git-config.txt-pushdefault) in the Git Docs.
+* If {% data variables.product.prodname_secret_scanning %} upon a push times out, {% data variables.product.prodname_dotcom %} will still run a scan after the push.
+
+{% endnote %}
+
+### Allowing a blocked secret to be pushed
+
+If {% data variables.product.prodname_dotcom %} blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.
+
+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. For example, you might revoke the secret and remove the secret from the repository's commit history. For more information, see "[Removing sensitive data from a repository](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)."
+
+When you allow a secret to be pushed, an alert is created in the "Security" tab. The alert is closed and no notifications are sent if you specify that the secret is a false positive or used only in tests. If you specify that the secret is real and that you will fix it later, the security alert remains open and notifications are sent to the author of the commit and repository administrators. For more information, see "[Managing alerts from secret scanning](/code-security/secret-scanning/managing-alerts-from-secret-scanning)."
+
+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)
+2. Choose the option that best describes why you should be able to push the secret.
+    - If the secret is only used in tests and poses no threat, click **It's used in tests**.
+    - If the detected string is not a secret, click **It's a false positive**.
+    - If the secret is real but you intend to fix it later, click **I'll fix it later**.
+3. Click **Allow me to push this secret**.
+4. Reattempt the push on the command line within three hours. If you have not pushed within three hours, you will need to repeat this process.

content/get-started/learning-about-github/about-github-advanced-security.md

@@ -26,7 +26,7 @@ A {% data variables.product.prodname_GH_advanced_security %} license provides th
 
 - **{% data variables.product.prodname_code_scanning_capc %}** - Search for potential security vulnerabilities and coding errors in your code. For more information, see "[About {% data variables.product.prodname_code_scanning %}](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)."
 
-- **{% data variables.product.prodname_secret_scanning_caps %}** - Detect secrets, for example keys and tokens, that have been checked into the repository. For more information, see "[About {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/about-secret-scanning)."
+- **{% data variables.product.prodname_secret_scanning_caps %}** - Detect secrets, for example keys and tokens, that have been checked into the repository.{% if secret-scanning-push-protection %} If push protection is enabled, also detects secrets when they are pushed to your repository. For more information, see "[About {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/about-secret-scanning)" and "[Protecting pushes with {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)."{% else %} For more information, see "[About {% data variables.product.prodname_secret_scanning %}](/code-security/secret-scanning/about-secret-scanning)."{% endif %}
 
 {% ifversion fpt or ghes > 3.1 or ghec or ghae-issue-4864 %}
 - **Dependency review** - Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. For more information, see "[About dependency review](/code-security/supply-chain-security/about-dependency-review)."

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

@@ -0,0 +1,6 @@
+# Reference: #5620.
+# Documentation for secret scanning as a push protection
+versions:
+  ghes: '>=3.5'
+  ghae: 'issue-5620'
+  ghec: '*'

data/reusables/advanced-security/secret-scanning-push-protection-org.md

@@ -0,0 +1,3 @@
+1. Under "{% data variables.product.prodname_secret_scanning_caps %}", under "Push protection", click **Enable all**.
+   ![Screenshot showing how to enable push protection for {% data variables.product.prodname_secret_scanning %} for an organization](/assets/images/help/organizations/secret-scanning-enable-push-protection.png)
+1. Optionally, click "Automatically enable for private repositories added to {% data variables.product.prodname_secret_scanning %}."

data/reusables/advanced-security/secret-scanning-push-protection-repo.md

@@ -0,0 +1,2 @@
+1. Under "{% data variables.product.prodname_secret_scanning_caps %}", under "Push protection", click **Enable**.
+   ![Screenshot showing how to enable push protection for {% data variables.product.prodname_secret_scanning %} for a repository](/assets/images/help/repository/secret-scanning-enable-push-protection.png)

data/reusables/gated-features/secret-scanning.md

@@ -1,4 +1,4 @@
-<!--This reusable describes the GHAS secret scanning feature. For a reusable that also covers the free secret scanning for public repositories on GitHub.com, use `secret-scanning-parter.md`  -->
+<!--This reusable describes the GHAS secret scanning feature. For a reusable that also covers the free secret scanning for public repositories on GitHub.com, use `secret-scanning-partner.md`  -->
 
 {%- ifversion ghec or ghes %}
 {% data variables.product.prodname_secret_scanning_GHAS_caps %} is available for organization-owned repositories in {% data variables.product.product_name %} if your enterprise has a license for {% data variables.product.prodname_GH_advanced_security %}.

data/reusables/rest-reference/secret-scanning/secret-scanning.md

@@ -2,7 +2,7 @@
 
 The {% data variables.product.prodname_secret_scanning %} API lets you{% ifversion fpt or ghec or ghes > 3.1 or ghae %}:
 
-- Enable or disable {% data variables.product.prodname_secret_scanning %} for a repository. For more information, see "[Repositories](/rest/reference/repos#update-a-repository)" in the REST API documentation.
+- Enable or disable {% data variables.product.prodname_secret_scanning %}{% if secret-scanning-push-protection %} and push protection{% endif %} for a repository. For more information, see "[Repositories](/rest/reference/repos#update-a-repository)" and expand the "Properties of the `security_and_analysis` object" section in the REST API documentation.
 - Retrieve and update {% data variables.product.prodname_secret_scanning_GHAS %} alerts from a repository. For further details, see the sections below.
 {%- else %} retrieve and update {% data variables.product.prodname_secret_scanning %} alerts from a repository.{% endif %}
 

data/reusables/secret-scanning/partner-program-link.md

@@ -1,5 +1,5 @@
 {% ifversion fpt or ghec %}
 To find out about our partner program, see "[{% data variables.product.prodname_secret_scanning_caps %} partner program](/developers/overview/secret-scanning-partner-program)."
 {% else %}
-To find out about our partner program, see "[{% data variables.product.prodname_secret_scanning_caps %} partner program](/free-pro-team@latest/developers/overview/secret-scanning-partner-program)" in the {% data variables.product.prodname_ghe_cloud %} documentation
+To find out about our partner program, see "[{% data variables.product.prodname_secret_scanning_caps %} partner program](/enterprise-cloud@latest/developers/overview/secret-scanning-partner-program)" in the {% data variables.product.prodname_ghe_cloud %} documentation.
 {% endif %}

data/reusables/secret-scanning/push-protection-beta.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** {% data variables.product.prodname_secret_scanning_caps %} as a protection push is currently in beta and subject to change. To request access to the beta release, [contact your account management team](https://github.com/enterprise/contact).
+
+{% endnote %}

data/reusables/secret-scanning/push-protection-overview.md

@@ -0,0 +1 @@
+When you enable push protection, {% data variables.product.prodname_secret_scanning %} also checks pushes for high-confidence secrets (those identified with a low false positive rate). {% data variables.product.prodname_secret_scanning_caps %} lists any secrets it detects so the author can review the secrets and remove them or, if needed, allow those secrets to be pushed.