Working with push protection

About working with push protection

Push protection prevents you from accidentally committing secrets to a repository by blocking pushes containing supported secrets.

You can work with push protection from the command line or from the web UI.

For more information on working with push protection, including how to bypass the block if necessary, see "Using push protection from the command line" and "Using push protection from the web UI" in this article.

Using push protection from the command line

When you attempt to push a supported secret to a repository secured by push protection, GitHub will block the push. You can remove the secret from your branch 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, GitHub will not block that secret.

If you confirm a secret is real, you need to remove the secret from your branch, from all the commits it appears in, before pushing again. For more information about remediating blocked secrets, see "Pushing a branch blocked by push protection."

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. Real secrets that have been exposed must be revoked to avoid unauthorized access. You might consider first rotating the secret before revoking it. For more information, see "Removing sensitive data from a repository."

In some cases, you may need to bypass the block on a secret. For more information on how to bypass push protection and push a blocked secret, see "Bypassing push protection when working with the command line."

Bypassing push protection when working with the command line

If GitHub blocks a secret that you believe is safe to push, you can bypass the block by specifying a reason for allowing the secret to be pushed.

When you allow a secret to be pushed, an alert is created in the Security tab. GitHub closes the alert and doesn't send a notification 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, GitHub keeps the security alert open and sends notifications to the author of the commit, as well as to repository administrators. For more information, see "Managing alerts from secret scanning."

When a contributor bypasses a push protection block for a secret, GitHub also sends an email alert to the organization owners, security managers, and repository administrators who have opted in for email notifications.

1. Visit the URL returned by GitHub when your push was blocked.

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.

   Note: You are required to specify a reason for bypassing push protection if the repository has secret scanning enabled.

   When pushing to a public repository that doesn't have secret scanning enabled, you are still protected from accidentally pushing secrets thanks to push protection for users, which is on by default for your user account.

   With push protection for users, GitHub will automatically block pushes to public repositories if these pushes contain supported secrets, but you won't need to specify a reason for allowing the secret, and GitHub won't generate an alert. For more information, see "Push protection for users."

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.

Using push protection from the web UI

When you use the web UI to attempt to commit a supported secret to a repository secured by push protection, GitHub will block the commit.

You will see a dialog box with information about the secret's location, as well as options allowing you to push the secret. The secret will also be underlined in the file so you can easily find it.

For a blocked commit, you can remove the secret from the file using the web UI. Once you remove the secret, you will be able to commit your changes.

GitHub will also block the commit if you attempt to upload files containing supported secrets. The dialog box will show you which files contain the secret. You should remove the secret from the files before attempting to upload the files again.

GitHub will only display one detected secret at a time in the web UI. If a particular secret has already been detected in the repository and an alert already exists, GitHub will not block that secret.

Organization owners can provide a custom link that will be displayed when a push is blocked. This custom link can contain resources and advice specific to your organization. For example, the custom link can point to a README file with information about the organization's secret vault, which teams and individuals to escalate questions to, or the organization's approved policy for working with secrets and rewriting commit history.

You can bypass the block by specifying a reason for allowing the secret. For more information on how to bypass push protection and commit the blocked secret, see "Bypassing push protection when working with the web UI."

Bypassing push protection when working with the web UI

If you confirm a secret is real, you need to remove the secret from your branch, from all the commits it appears in, before pushing again. For more information about remediating blocked secrets, see "Pushing a branch blocked by push protection."

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 more information, see "Removing sensitive data from a repository."

If GitHub blocks a secret that you believe is safe to commit, you can bypass the block by specifying a reason for allowing the secret.

When you allow a secret to be pushed, an alert is created in the Security tab. GitHub closes the alert and doesn't send a notification 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, GitHub keeps the security alert open and sends notifications to the author of the commit, as well as to repository administrators. For more information, see "Managing alerts from secret scanning."

When a contributor bypasses a push protection block for a secret, GitHub also sends an email alert to the organization owners, security managers, and repository administrators who have opted in for email notifications.

1. In dialog box that appeared when GitHub blocked your commit, review the name and location of the secret.

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.

   Note: You are required to specify a reason for bypassing push protection if the repository has secret scanning enabled.

   When pushing to a public repository that doesn't have secret scanning enabled, you are still protected from accidentally pushing secrets thanks to push protection for users, which is on by default for your user account.

   With push protection for users, GitHub will automatically block pushes to public repositories if these pushes contain supported secrets, but you won't need to specify a reason for allowing the secret, and GitHub won't generate an alert. For more information, see "Push protection for users."

3. Click Allow secret.

Further reading

• "Pushing a branch blocked by push protection"
• "Push protection for repositories and organizations"