|
| 1 | +--- |
| 2 | +title: Protecting pushes with secret scanning |
| 3 | +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.' |
| 4 | +product: '{% data reusables.gated-features.secret-scanning %}' |
| 5 | +miniTocMaxHeadingLevel: 3 |
| 6 | +versions: |
| 7 | + feature: 'secret-scanning-push-protection' |
| 8 | +redirect_from: |
| 9 | + - /early-access/code-security/secret-scanning/protecting-pushes-with-secret-scanning |
| 10 | +type: how_to |
| 11 | +topics: |
| 12 | + - Secret scanning |
| 13 | + - Advanced Security |
| 14 | + - Alerts |
| 15 | + - Repositories |
| 16 | +shortTitle: Push protection |
| 17 | +--- |
| 18 | + |
| 19 | +{% data reusables.secret-scanning.beta %} |
| 20 | +{% data reusables.secret-scanning.enterprise-enable-secret-scanning %} |
| 21 | +{% data reusables.secret-scanning.push-protection-beta %} |
| 22 | + |
| 23 | +## About push protection for secrets |
| 24 | + |
| 25 | +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 %} |
| 26 | + |
| 27 | +{% data variables.product.prodname_secret_scanning_caps %} as a push protection currently scans repositories for secrets issued by the following service providers. |
| 28 | + |
| 29 | +{% data reusables.secret-scanning.secret-list-private-push-protection %} |
| 30 | + |
| 31 | +## Enabling {% data variables.product.prodname_secret_scanning %} as a push protection |
| 32 | + |
| 33 | +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)." |
| 34 | + |
| 35 | +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. |
| 36 | + |
| 37 | +### Enabling {% data variables.product.prodname_secret_scanning %} as a push protection for an organization |
| 38 | + |
| 39 | +{% data reusables.organizations.navigate-to-org %} |
| 40 | +{% data reusables.organizations.org_settings %} |
| 41 | +{% data reusables.organizations.security-and-analysis %} |
| 42 | +{% data reusables.repositories.navigate-to-ghas-settings %} |
| 43 | +{% data reusables.advanced-security.secret-scanning-push-protection-org %} |
| 44 | + |
| 45 | +### Enabling {% data variables.product.prodname_secret_scanning %} as a push protection for a repository |
| 46 | + |
| 47 | +{% data reusables.repositories.navigate-to-repo %} |
| 48 | +{% data reusables.repositories.sidebar-settings %} |
| 49 | +{% data reusables.repositories.navigate-to-security-and-analysis %} |
| 50 | +{% data reusables.repositories.navigate-to-ghas-settings %} |
| 51 | +{% data reusables.advanced-security.secret-scanning-push-protection-repo %} |
| 52 | + |
| 53 | + |
| 54 | +## Using {% data variables.product.prodname_secret_scanning %} as a push protection from the command line |
| 55 | + |
| 56 | +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. |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | + |
| 61 | + |
| 62 | +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. |
| 63 | + |
| 64 | +{% note %} |
| 65 | + |
| 66 | +**Notes**: |
| 67 | + |
| 68 | +* 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. |
| 69 | +* 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. |
| 70 | + |
| 71 | +{% endnote %} |
| 72 | + |
| 73 | +### Allowing a blocked secret to be pushed |
| 74 | + |
| 75 | +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. |
| 76 | + |
| 77 | +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)." |
| 78 | + |
| 79 | +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)." |
| 80 | + |
| 81 | +1. Visit the URL returned by {% data variables.product.prodname_dotcom %} when your push was blocked. |
| 82 | +  |
| 83 | +2. Choose the option that best describes why you should be able to push the secret. |
| 84 | + - If the secret is only used in tests and poses no threat, click **It's used in tests**. |
| 85 | + - If the detected string is not a secret, click **It's a false positive**. |
| 86 | + - If the secret is real but you intend to fix it later, click **I'll fix it later**. |
| 87 | +3. Click **Allow me to push this secret**. |
| 88 | +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. |
0 commit comments