Secret scanning basics

Lena Fischer started at Tidewater as the summer developer on March 29, three weeks earlier than planned because the TrailCheck release needed help. On her first afternoon she tried to push a change that added a map to the trail-report page, and GitHub refused it. The message said the push contained a secret: the access key for the map tile service, copied into a configuration file from the setup notes. Lena was embarrassed; Priya was delighted. "That is the best thing that could have happened on your first day," she said, and turned the Monday session into a lesson on secret scanning and push protection, using Lena's blocked push as the example.

What a secret is and why it leaks

In this context a secret is any value that grants access: a password, an API key for a service such as a map provider or a payment processor, a cloud access key, a token for GitHub itself, a private key for signing or encryption, or a database connection string with a password in it. Anyone who has the secret can act as its owner, usually without any further check. Secrets leak into repositories in ordinary ways: pasted into a configuration file to get something working quickly, left in a test, included in an example, committed in a file that should have been in .gitignore, or posted in an issue while asking for help.

A leak in Git is stubborn. Deleting the file in a later commit does not remove the secret from history, where anyone who can read the repository can still find it, and a public repository may have been cloned or forked before anyone noticed. Automated tools scan public repositories constantly for keys, so a secret pushed to a public repository can be found and misused within minutes. That is why the response to a leak always starts with the secret itself, not with the repository.

What secret scanning does

Secret scanning searches a repository for strings that match the known formats of secrets from hundreds of service providers. It scans the entire Git history of every branch, not only the latest files, and also issues, pull requests, discussions and wikis. When it finds a match, it raises a secret scanning alert on the repository's Security tab, showing the type of secret, where it was found, and when. GitHub rescans repositories when it adds support for new types of secret.

For public repositories, two things happen automatically and for free. Through the secret scanning partner program, when GitHub finds a secret belonging to a participating provider, it notifies that provider, which can revoke the key or warn its customer; this happens even if the repository owner has not turned anything on. And repository owners receive user alerts for secrets found in their repositories, so they can act themselves. For private and internal repositories owned by organizations, secret scanning is part of GitHub Secret Protection (lesson 7).

Beyond the providers' own formats, secret scanning can also look for generic secrets, such as private keys, connection strings and passwords that do not follow a provider's pattern, some of them found with AI-based detection; organizations can define custom patterns for their own internal formats. Validity checks ask the provider whether a found secret is still active, so the team can tell a dangerous live key from an old one that was already revoked.

Push protection

Secret scanning finds secrets that are already in a repository. Push protection stops them getting there. When someone pushes commits, GitHub checks them for supported secrets before accepting the push; if it finds one, it blocks the push and tells the person which file, which line and which type of secret, with links explaining what to do. The same check runs when someone edits a file in the web interface. For personal accounts, push protection for users is on by default for pushes to any public repository, which is what stopped Lena, and repositories and organizations can turn push protection on for their own repositories.

The person whose push was blocked has a choice. The right response, almost always, is to remove the secret from the commits and push again. If the value really is not a live secret, they can bypass the block by giving a reason: the value is used only in tests, it is a false positive, or the secret will be fixed later. A bypass lets the push through, records who bypassed and why, and creates an alert so that someone checks. Organizations can require delegated bypass, in which a bypass is only a request that a named reviewer must approve.

Keeping secrets out of code

Push protection is a safety net, not the plan. The plan is that secrets never go into files that Git tracks. Configuration that varies between computers, including keys, belongs in environment variables or a local file listed in .gitignore. Automated workflows read secrets from GitHub Actions secrets, which are stored encrypted, available only to workflows, and hidden in logs. Codespaces have their own encrypted secrets. Teams keep the real values in a password manager or a secrets service, and repositories hold only placeholders and instructions. Example and test files use obviously fake values.

How workflows use secrets safely

GitHub Actions workflows often need secrets: the TrailCheck deployment needs the map key at build time, and the trail-report validator needs a token to post results. An administrator stores each value once as an Actions secret, at the repository, environment or organization level, and the workflow file refers to it only by name, such as MAP_KEY. GitHub supplies the value to the running job, never shows it in the web interface again, and replaces it with asterisks if it appears in a log. Secrets are not passed to workflows triggered by pull requests from forks, so an outside contributor cannot write a workflow that prints them. Environment secrets can additionally require an approval before a job that uses them may run, which Tidewater uses for the production deployment.

Two habits keep this arrangement safe. Give each workflow the narrowest secret it needs, for example a key that can only read map tiles rather than one that can also change the account, and rotate long-lived secrets on a schedule, recorded in the admin repository. Where a cloud provider supports it, workflows can avoid stored secrets altogether by using OpenID Connect, in which the workflow proves its identity to the provider and receives a short-lived credential for that run only; the cloud courses cover this in detail.

Screenshots are the one case secret scanning cannot help with, because it reads text, not images. Grace added a line to the contributing guide asking everyone to check screenshots of settings pages before attaching them, after a test screenshot in a draft pull request showed most of an email service password.

Responding to a leaked secret

If a secret does reach GitHub, the order of the response matters. First, revoke or rotate the secret at the service that issued it, so the leaked value stops working; this is the only step that actually removes the risk, and it should happen before anything else. Second, check for misuse, using the provider's logs to see whether the key was used by anyone else while it was exposed. Third, update everything that legitimately used the old secret with the new one, stored properly. Fourth, close the alert with a note of what was done. Removing the secret from Git history is a fifth and optional step: it is slow, it disrupts everyone who has cloned the repository, and it achieves little once the secret has been revoked, because the old value no longer works.

Secret scanning in a small organization

For Tidewater, the decision about the paid product came down to numbers. Public repositories, which hold most of the code, already had secret scanning and push protection at no cost. The free secret risk assessment that Rosa ran in April scanned the private repositories and found two secrets, both old keys for services the company no longer used, both already inactive according to the providers. Rather than buy GitHub Secret Protection for one private code repository, the team revoked the two keys formally, moved the private repository's configuration to Actions secrets, and agreed to repeat the assessment every six months.

Owen asked what he should remember for the exam. Priya's summary was three sentences: secret scanning finds secrets that are already in a repository, push protection stops new ones getting in, and when a secret leaks, the first step is always to revoke it.