How to Set Up GitHub Secret Scanning

A stray API key in a commit can turn a routine push into a security incident. GitHub secret scanning looks for exposed credentials in code, then alerts your team so you can act. Use these steps to set the right scope, route alerts, block risky pushes, and manage any leaked key.

Step 1: Check Repository Eligibility and Choose Your Scope

First decide which repositories need coverage and who will own the alerts. Secret scanning uses pattern matching to find known credentials, such as tokens and API keys, in repository content. It scans Git history across branches and can rescan when GitHub adds new secret types.

For user accounts, secret scanning alerts can be enabled on free public repositories. Organization-owned repositories are also eligible. Some features have plan or license requirements, so check eligibility before rolling out custom patterns or partner validity checks across an organization.

Start with one repository if you’re testing the workflow. For wider coverage, an organization owner can use security configurations to enable features across multiple repositories. An enterprise owner can also set coverage at the enterprise level. Enterprise public monitoring is a separate setting. It can scan public repositories across GitHub for secrets tied to enterprise members or users with an email address on the enterprise’s verified domain.

Detection has limits worth knowing before you read an alert report. Some credentials use a paired pattern, such as an access key ID and a matching secret. Both parts must be pushed to the same repository and found in the same file for GitHub to detect that pair. Pattern-pair requirements and push protection can affect what secret scanning detects.

Keep GitHub detection separate from the place where your team stores active credentials. EnvManager encrypts and version-controls .env files, then manages team access and syncing. That gives developers a managed route for shared values instead of copying keys into code or chat. A wider secrets management process helps define who can use each value.

By now you should have a repository list, an owner for security alerts, and a decision on whether public monitoring is in scope.

Step 2: Enable Secret Scanning for Repositories

Turn on Secret Protection for the repositories you selected. For a single repository, open its main page on GitHub. Select Settings, then choose Advanced Security under Security and quality. Beside Secret Protection, choose Enable. Review the effect, then confirm Enable Secret Protection.

If the Settings tab isn’t visible, open the repository menu and select it there. You’ll need the right repository or organization permissions to change security settings. An organization owner can also apply security configurations to a group of repositories instead of turning the feature on one repo at a time.

After activation, GitHub scans the repository’s history across its branches. That’s useful when a key was committed months ago and no longer appears in the current file. Don’t assume an empty alert list means every past credential is safe. Confirm that the repositories you meant to protect actually have Secret Protection enabled.

Default patterns cover known secret types. If your team uses a private token format, define a custom pattern with a name and a regular expression. You can use AI to draft a regex from a description, but test the match before publishing it.

For a repository pattern, go to Settings, then Advanced Security. Under Secret Protection, choose New pattern. Save it as a dry run first. GitHub shows a sample of matches, so inspect results for false positives and adjust the expression before publishing.

When secrets need to reach build jobs, keep them out of committed files. The workflow for GitHub Actions secrets can help you choose how to pass values to a run without placing them in source code.

By now, scanning should be active on the selected repositories, and any custom pattern should have passed a dry run before publication.

Step 3: Configure Alerts and Notification Workflows

An alert only helps if someone sees it and knows what to do next. GitHub displays secret scanning alerts in the repository’s Security and quality area. It can also send email notifications based on access and notification preferences.

To watch security alerts for a repository, choose Watch, then select Custom and turn on Security alerts. You can also set email delivery in your account’s notification settings. Commit authors who accidentally add a secret may receive a notification even if their usual preferences would not send one.

Historical scans use a different notification path from new detections. GitHub does not notify commit authors for historical scan alerts. Make sure your team’s process checks the alert list after enabling scanning, rather than waiting for an email to reveal older exposures.

Set an owner or response group for every alert. For a small team, that might be the repository owner. For a larger organization, route new alerts to the security team and record who will rotate the affected credential. A webhook can send secret-scanning alert events to a system your team already monitors. A connected tool can also provide recent validity status for tokens.

Validity checks can help rank the work. GitHub checks GitHub token status by default. Eligible organizations can enable checks for supported partner patterns, then use the alert view to see whether a credential appears active. An active key should move to the front of the queue.

Keep the workflow simple: assign an owner, set a response target your team can meet, and record the action taken. That record helps the next person understand whether a key was rotated, verified, or closed as a false positive.

By now, new alerts should have a route to a person or team, not just a place in the GitHub interface.

Step 4: Turn On Push Protection and Set Bypass Controls

Secret scanning finds exposed values after they enter a repository. Push protection tries to stop supported secrets before that happens. It blocks a push when it detects a potential secret and gives the contributor a message explaining the block.

To enable it for a repository, open Settings, then Advanced Security. If Secret Protection is off, enable it first. In the Secret Protection area, choose Enable beside Push protection. Organizations and enterprises can also manage protection at a broader scope.

Ask developers to remove the sensitive value and retry the push. They should replace it with a safe reference to a secret stored outside the repository. For a custom pattern, publish and test the pattern before enabling push protection for it.

Decide who may bypass a block before rollout. By default, a user with write access can bypass push protection by giving a reason. A bypass creates an alert, so it should trigger review rather than quietly end the discussion. If that default is too broad, configure delegated bypass to limit who can approve an exception.

Use bypasses only for a known, reviewed case. A test fixture may look like a credential but contain no usable value. In that case, record why the push was allowed and check the resulting alert. For an actual key, stop and remove it instead. A brief team rule for API key handling can reduce repeat blocks caused by values copied into source.

By now, supported secrets should be blocked at push time, and contributors should know how to request or document an exception.

Step 5: Remediate Alerts and Prevent Recurrence

Treat a committed secret as compromised, even if the repository is private. Removing the text from the latest commit does not make the exposed credential safe. First revoke or rotate it with the service that issued it.

Then check where the old value was used. Update the app, deployment settings, or CI workflow with the replacement. If the same key appears in more than one place, plan each update so the change doesn’t break a production job. EnvManager can help teams keep replacement environment values in one encrypted, version-controlled place and sync them to local machines or CI/CD pipelines.

Review the alert details and locations, then check whether the credential may still be active. GitHub can validate some supported patterns. For a public repository, partner providers may be notified when their pattern is detected and may take action, such as revoking the credential. Those partner reports are sent to the provider and don’t appear as repository alerts.

After rotation, remove the exposed value from current files and assess whether history cleanup is needed. GitHub notes that rewriting history can take time and may not be needed once a credential has been revoked. Coordinate with contributors before rewriting shared history, since they may need to rebase or reclone.

Close the alert after you’ve fixed the issue. GitHub doesn’t close it just because the value was removed from the repository. Open the alert list, select the alert, then choose a close reason. Add a short comment when it helps explain the rotation or dismissal. A secret rotation plan can set clear owners and make future changes easier to track.

Keep the response record with the alert. Note the affected service, who rotated the value, and where the replacement now lives. That gives the next responder a useful trail without copying the secret into the record.

By now, the old credential should be revoked or rotated, its uses updated, and the alert closed with a clear reason.

GitHub Secret Scanning FAQ

What is GitHub secret scanning?

GitHub secret scanning is a feature that checks repository content for known credentials, such as API keys and tokens. It uses pattern matching and can scan Git history across branches. When it finds a potential leak, it creates an alert so someone can assess the value and respond.

Does secret scanning check old commits?

Yes, GitHub scans the repository’s Git history across branches when secret scanning is enabled. It also periodically rescans repositories when it adds secret types. A clean current file doesn’t prove an old key was never committed, so review historical alerts after turning the feature on.

Does secret scanning stop a secret from being pushed?

Push protection can block supported secrets before they reach the repository. It works alongside secret scanning, which detects potential leaks and creates alerts. Contributors may be able to bypass a block, depending on the repository settings, so review bypass events and keep the reason with the alert.

What should I do when GitHub finds a secret?

Assume the credential is exposed and revoke or rotate it first. Then update the systems that use it, review the alert locations, and remove the value from code. Close the alert manually after remediation, since deleting a value from the repository doesn’t automatically close its alert.

Conclusion

Enable scanning across the repositories that hold active code, then add push protection where your team can manage bypasses. Start by turning it on for one repository and confirming that alerts reach an owner. Keep active credentials in a managed secret store, not in source files.