Get the free coreGet core

GitHub secret scanning and push protection explained

Updated 4 min readSection 05 / Threats
SHORT ANSWER

GitHub secret scanning is a GitHub feature that searches the entire Git history on all branches of a repository for hardcoded credentials such as API keys, passwords and tokens. It is free and automatic on public repositories; for private repositories it depends on who the repository belongs to and on the plan. Push protection is a second feature that blocks a push containing a secret before it reaches the repository. At the repository level it is off by default. An alert means the key is exposed: revoke it first.

You will meet GitHub secret scanning in two places: as alerts on a repository, and as a blocked push in your terminal. They are two features that work together, and this page covers both.

01What GitHub secret scanning detects

It looks for known secret types, which are credential formats from many providers, across your entire Git history on all branches. Three details help you read the results.

Alerts appear in the Security and quality tab of the repository. Validity checks show whether a detected secret is still active, which helps you decide what to fix first.

Partner secrets are keys issued by other companies. GitHub notifies the company so it can act, such as revoking the credential, and does not display these in your repository alerts. A valid OAuth token, GitHub App token or personal access token pushed to a public repository or public gist, a small shareable snippet on GitHub, is revoked automatically. A revoked token cannot be restored, so you create a new one.

02Who can use it

What you get depends on the type of repository and your plan.

RepositorySecret scanning
PublicRuns automatically for free
Organization-owned private or internalAvailable with GitHub Secret Protection enabled on Team or Enterprise Cloud
User-owned private (a repository on a personal account)Available on Enterprise Cloud with Enterprise Managed Users, and on Enterprise Server when the enterprise has GitHub Secret Protection enabled

Check the Settings of your repository to see what your account offers.

03How to turn it on

To switch on the scanner, open the repository Settings. In the Security and quality section of the sidebar, click Advanced Security. To the right of Secret Protection, click Enable. If you do not see the option, your plan or repository type may not include it.

Push protection is a separate setting. At the repository level it is disabled by default, and a repository administrator, an organization owner, a security manager or an enterprise owner can enable it.

04What push protection does

Scanning tells you after the fact. Push protection blocks pushes that contain secrets before they reach the repository. When it detects a potential secret during a push, it blocks the push and explains why. You review the code, remove the sensitive information and try again.

There is a second kind tied to your account. Push protection for users prevents you from accidentally pushing supported secrets to any public repository. It is on by default for your user account, and it works even on a public repository that has secret scanning turned off.

If the key is in your most recent commit, remove it from the file and fold the fix into that commit with this documented command:

git commit --amend --all

It updates the original commit that introduced the secret instead of creating a new one. Anything buried deeper in history needs the history cleanup steps.

05Bypassing a block

A bypass means pushing anyway after a block. For repositories, by default anyone with write access can bypass push protection by giving a reason. GitHub returns a URL when it blocks your push. Visit it as the same user who pushed; anyone else gets a 404. After that, retry the push within three hours or repeat the process. Bypassed pushes are listed by filtering alerts with bypassed: true. Treat a bypass as a decision to ship the value on purpose, and use it only for a test value.

06What it does not do

Scanning is a net, and nets have holes. Older versions of some tokens may not be supported by push protection, because they may produce more false positives. And finding a key does not make it safe.

Consider any leaked secret immediately compromised. Removing it from the codebase, pushing a new commit, or deleting and recreating the repository does not prevent it from being exploited. The most important step is revoking the secret with its provider, which usually means logging into the provider's portal and finding where the secret is managed. The order of steps, including how to avoid downtime, is on the page about a leaked key. Hour-by-hour steps for a public repository are on a key exposed on GitHub.

07Running a scanner of your own as well

GitHub only sees what you push, so a scan on your own machine can catch a key sooner. Secret scanning in general compares the options. TruffleHog is covered with commands, and the GitGuardian alternatives page puts ggshield and git-secrets beside GitHub's scanner. The earliest fix is a key that never sits in the repository, as described under where to store API keys.

08The short version

GitHub secret scanning reads your history and raises alerts. Push protection stops the push. Secret scanning is free on public repositories, and the plan and owner decide the rest. When either one fires, revoke the key before you do anything else.

FAQ

What is secret scanning in GitHub?

A GitHub feature that scans your entire Git history on all branches for hardcoded credentials, including API keys, passwords and tokens. When it finds one it generates an alert.

Is GitHub secret scanning free?

On public repositories it runs automatically for free. Organization-owned private repositories need GitHub Secret Protection on GitHub Team or Enterprise Cloud.

How do I turn on GitHub secret scanning?

Open the repository Settings, click Advanced Security in the Security and quality section of the sidebar, and click Enable to the right of Secret Protection. Where the option appears depends on your plan.

What does push protection do?

It blocks pushes that contain secrets before they reach your repository. You then remove the secret and push again.

Does GitHub find every key I commit?

No. Older versions of some tokens may not be covered by push protection, and a paired credential raises an alert only when both parts are in the same file.

What should I do when I get an alert?

Revoke the key with its provider. Removing it from the code or deleting the repository does not stop it being exploited.

Sources

  1. GitHub docs, about secret scanning
  2. GitHub docs, about push protection
  3. GitHub docs, enabling secret scanning for your repository
  4. GitHub docs, about alerts
  5. GitHub docs, working with push protection from the command line
  6. GitHub docs, remediating a leaked secret
Alerts tell you about a key after the fact. Artificial Immunity watches program starts on the Mac where your agents work and reports what it finds.Get the free core