Skip to main content

Protecting pushes with secret scanning

You can use secret scanning to prevent supported secrets from being pushed into your enterprise, organization, or repository by enabling push protection.

Secret scanning for advanced security is available for organization-owned repositories in GitHub Enterprise Cloud if your enterprise has a license for GitHub Advanced Security. For more information, see "About GitHub Advanced Security."

Note: Secret scanning as a protection push is currently in beta and subject to change. To request access to the beta release, contact your account management team.

About push protection for secrets

Up to now, secret scanning for advanced security checks for secrets after a push and alerts users to exposed secrets. When you enable push protection, secret scanning also checks pushes for high-confidence secrets (those identified with a low false positive rate). Secret scanning lists any secrets it detects so the author can review the secrets and remove them or, if needed, allow those secrets to be pushed.

If a contributor bypasses a push protection block for a secret, GitHub:

  • creates an alert in the "Security" tab of the repository in the state described in the table below.
  • adds the bypass event to the audit log.
  • sends an email alert to organization owners, security managers, and repository administrators who are watching the repository, with a link to the secret and the reason why it was allowed.

This table shows the behavior of alerts for each way a user can bypass a push protection block.

Bypass reasonAlert behavior
It's used in testsGitHub creates a closed alert, resolved as "used in tests"
It's a false positiveGitHub creates a closed alert, resolved as "false positive"
I'll fix it laterGitHub creates an open alert

For information on the secrets and service providers supported for push protection, see "Secret scanning patterns."

Enabling secret scanning as a push protection

For you to use secret scanning as a push protection, the enterprise, organization, or repository needs to have both GitHub Advanced Security and secret scanning enabled. For more information, see "Managing security and analysis settings for your enterprise," "Managing security and analysis settings for your organization," "Managing security and analysis settings for your repository," and "About GitHub Advanced Security."

Organization owners, security managers, and repository administrators can enable push protection for secret scanning via the UI and API. For more information, see "Repositories" and expand the "Properties of the security_and_analysis object" section in the REST API documentation.

Enabling secret scanning as a push protection for your enterprise

  1. In the top-right corner of GitHub.com, click your profile photo, then click Your enterprises. "Your enterprises" in drop-down menu for profile photo on GitHub Enterprise Cloud

  2. In the list of enterprises, click the enterprise you want to view. Name of an enterprise in list of your enterprises

  3. In the enterprise account sidebar, click Settings. Settings tab in the enterprise account sidebar

  4. In the left sidebar, click Code security and analysis.

  5. Under "Secret scanning", under "Push protection", click Enable all.

    Screenshot showing how to enable push protection for secret scanning for an enterprise

  6. Optionally, click "Automatically enable for repositories added to secret scanning."

  7. Optionally, to include a custom link in the message that members will see when they attempt to push a secret, click Add a resource link in the CLI and web UI when a commit is blocked, then type a URL, and click Save link.

    Screenshot showing checkbox and text field for enabling a custom link

Enabling secret scanning as a push protection for an organization

  1. On GitHub.com, navigate to the main page of the organization.

  2. Under your organization name, click Settings.

    Organization settings button

  3. In the "Security" section of the sidebar, click Code security and analysis.

  4. Under "Code security and analysis", find "GitHub Advanced Security."

  5. Under "Secret scanning", under "Push protection", click Enable all. Screenshot showing how to enable push protection for secret scanning for an organization

  6. Optionally, click "Automatically enable for repositories added to secret scanning."

  7. Optionally, to include a custom link in the message that members will see when they attempt to push a secret, select Add a resource link in the CLI and web UI when a commit is blocked, then type a URL, and click Save link.

    Screenshot showing checkbox and text field for enabling a custom link

Enabling secret scanning as a push protection for a repository

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Settings. Repository settings button

  3. In the "Security" section of the sidebar, click Code security and analysis.

  4. Under "Code security and analysis", find "GitHub Advanced Security."

  5. Under "Secret scanning", under "Push protection", click Enable. Screenshot showing how to enable push protection for secret scanning for a repository

Using secret scanning as a push protection from the command line

When you attempt to push a supported secret to a repository or organization with secret scanning as a push protection enabled, 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.

Organization admins can provide a custom link that will be displayed when a push is blocked. This custom link can contain organization-specific resources and advice, such as directions on using a recommended secrets vault or who to contact for questions relating to the blocked secret.

Screenshot showing that a push is blocked when a user attempts to push a secret to a repository

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."

Notes:

  • If your git configuration supports pushes to multiple branches, and not only to the current branch, your push may be blocked due to additional and unintended refs being pushed. For more information, see the push.default options in the Git documentation.
  • If secret scanning upon a push times out, GitHub will still scan your commits for secrets after the push.

Allowing a blocked secret to be pushed

If GitHub blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.

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. Screenshot showing form with options for unblocking the push of a 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.
  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 secret scanning as a push protection from the web UI

When you use the web UI to attempt to commit a supported secret to a repository or organization with secret scanning as a push protection enabled, GitHub will block the commit.

You will see a banner at the top of the page with information about the secret's location, and the secret will also be underlined in the file so you can easily find it.

Screenshot showing commit in web ui blocked because of secret scanning push protection

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 admins 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 remove the secret from the file using the web UI. Once you remove the secret, the banner at the top of the page will change and tell you that you can now commit your changes.

Screenshot showing commit in web ui allowed after secret fixed

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

If GitHub blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.

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.

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 GitHub blocked your commit, click Bypass protection.

  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.

    Screenshot showing form with options for unblocking the push of a secret

  3. Click Allow secret.