Last year, in May 2023, GitHub announced the general availability of push protection, a feature that scans for highly identifiable secrets before they are pushed to public repositories. The feature is free for all public repositories and is now activated by default. However, there are some limitations to this feature, including the detection of only a few types of specific or prefixed secrets and the absence of historical scanning. To make an informed decision about whether this protective layer is sufficient for your needs, we have provided a detailed breakdown of these limitations. Transparency is key when it comes to security, and this information will help you make the best decision for your organization.
Since its inception in 2017, GitGuardian has been advocating for improved code security, particularly for open-source code, which is highly vulnerable due to its exposure to the public.
Guest Expert
GitHub, the largest open-source community, is a global hub for open-source code, and it’s also where the GitGuardian story started. The GitGuardian App eventually started gaining popularity, becoming the top security app on the GitHub marketplace.
Preventing secret leaks on GitHub's massive scale is a significant challenge with serious security implications for individuals and organizations across the world. We send over 5,000 pro-bono emails daily to alert contributors after detecting a hard-coded secret in their patches.
In Feb 2024, GitHub stepped up in protecting open source by enabling push protection by default for all public repositories, which is a big step forward in enhancing code hygiene. 🎉 On March 1, 2024, they initiated the deployment of push protection for all users. It may take a week or two to roll out to all accounts.
In this blog, we'll provide a summary of what to expect from this feature and its limitations. Our aim is to assist you in determining whether this protective layer is sufficient for your specific situation.
What is GitHub Push Protection?
Push protection prevents secret leaks by scanning for highly identifiable secrets before they are pushed.
“When a secret is detected in code, developers are prompted directly in their IDE or command line interface with remediation guidance to ensure that the secret is never exposed.”
Essentially what it means is that any leaky commit pushed to a remote branch will be blocked by GitHub, impeding the leaked credentials from sprawling on the Git server. The remote then refuses the push and responds with information about the leak, like this:
Developers will have the choice to either eliminate the secret from their commits or proceed if it's deemed safe.
It is important to note that previously, the push protection feature required activation through the dashboard to be effective. However, following this announcement by GitHub, it will now be enabled by default.
GitHub provides the commit contributor the option to bypass the push protection by following a URL. If a contributor bypasses a push protection block for a secret, GitHub:
- Creates an alert in the Security tab of the repository, adds the bypass event to the audit log,
- Sends an email alert to the organization or personal account owners, security managers, and repository administrators who are watching the repository, with a link to the secret and the reason why it was allowed.
How to Enable GitHub Push Protection: Step-by-Step Configuration
While GitHub push protection is now enabled by default for public repositories, understanding the configuration process remains crucial for organizations managing private repositories or requiring custom settings. The GitHub secret scanning push protection feature can be activated at multiple levels to provide comprehensive coverage.
For repository-level activation, navigate to your repository's Settings tab, select "Code security and analysis," and toggle push protection under the Secret scanning section. Organization owners can enable push protection across all repositories by accessing Organization settings, selecting "Code security and analysis," and configuring the feature organization-wide. This centralized approach ensures consistent protection across your entire codebase.
Enterprise administrators have additional control through GitHub Advanced Security settings, where they can specify which secret patterns to include in push protection and configure custom detection rules. The GitHub Advanced Security push protection integration allows for granular control over which token types trigger blocking mechanisms, ensuring alignment with your organization's specific security requirements and compliance standards.
What You Need to Keep in Mind
Push Protection and Local History Rewrites
When the push protection triggers, the secret needs to be removed from all the commits it appears in. From the developer's perspective, this creates a lot of friction, as rewriting the local commit history is not a trivial task.
The best approach for a frictionless developer experience is to introduce secret scanning at the pre-commit stage, which will stop the secret from entering the VCS (git in this case) in the first place, sparing the developer from tedious work that can even worsen the situation.
No Git History Scanning
Push protection is a real-time detection mechanism that can effectively reduce the likelihood of a secret entering a remote Git branch. However, this can leave your organization with a false sense of security because you won't be able to detect secrets that were hard-coded in the past. This can leave your organization vulnerable, as it's not uncommon to see the historical scanning surface hundreds or even thousands of incidents, with many of them still exploitable.
To avoid any loophole in your security posture, we encourage you to assess your repositories' health by performing a historical scan of your repositories at least once, which is done automatically when integrating the GitGuardian platform with your sources.
Limitations of Secret Detection
According to GitHub,
“This feature proactively prevents leaks by scanning for secrets before 'git push' operations are accepted, and it works with 69 token types (API keys, private keys, secret keys, authentication tokens, access tokens, management certificates, credentials, and more) detectable with a low "false positive" detection rate.”
The list of detected token types contains popular service tokens such as AWS, Azure, and Stripe. But is it enough? If we look at the number of web APIs, it is estimated that in 2022 there were more than 24,000 in the world, and this number is growing very fast. New services appear every day, and some have the chance to gain in popularity at an explosive rate. Take, for example, the number of OpenAI API keys found in public commits in 2022:
Developer adoption is fast-paced, which means that it’s almost impossible to predict which service will be popular in the next 6 months from now. In fact, detecting new, previously unlisted tokens is a strong predictor of the emerging popularity of a given service provider.
Since the feature was announced last year, GitGuardian has already detected over 10 million leaked secrets on public repositories. With 420 detectors, GitGuardian offers broader coverage compared to GitHub, which has 254 detectors, and just 97 of them have push protection.
Not All Secrets Are Easily Identifiable
At first, limiting the detection capability to credentials with “a low false positive detection rate” sounds like a good idea. But there is a caveat. It means that many credentials are going to fall through the cracks. Why? Because not all credentials are easily identifiable.
In fact, In 2022, what we refer to as generic secrets accounted for no less than two-thirds (67%) of the secrets detected. (from the State of Secrets Sprawl 2023):
Guardians
In short, limiting secret detection to a set of secrets that are almost 100% certain to be secrets leaves room for undetected leaks. And GitHub push protection focuses on specific secrets, missing generic ones. It's important to keep this in mind as it's worse to assume complete immunity against a vulnerability only to realize later that it was only partially the case.
Ineffective for Private Repositories Made Public
Finally, an often overlooked type of leak occurs when a private or internal repository is intentionally or unintentionally made public. This is a sensitive event as it exposes the entire repository history where credentials could be discovered. Since it's disconnected from the git flow, only historical analysis of all the commits from all the branches of a repository can detect secret leaks.
It's important to note that push protection is ineffective if a private repository is made public.
Push scan has a size limit
GitHub's push protection feature imposes a size limit, meaning that if a push exceeds a certain threshold, typically 5 seconds, the system may timeout, resulting in missed scans. With millions of developers on the platform, GitHub opts not to block users during lengthy pushes to avoid overwhelming them. As a result, developers may bypass the push process in such cases.
GitHub Push Protection Bypass: Understanding Security Trade-offs
The GitHub push protection bypass mechanism represents a critical balance between security enforcement and developer productivity. When push protection detects a potential secret, developers encounter three bypass options: marking the detection as a false positive, indicating it's used in tests, or acknowledging they'll fix it later.
Each bypass reason triggers different alert behaviors within GitHub's security framework. False positive bypasses create closed alerts resolved as "false positive," while test-related bypasses generate closed alerts marked as "used in tests." However, selecting "I'll fix it later" creates an open alert that requires active remediation, maintaining visibility into unresolved security issues.
Organizations implementing delegated bypass for push protection can establish approval workflows where designated security reviewers must authorize bypass requests. This approach prevents unauthorized secret exposure while maintaining development velocity. The bypass event generates comprehensive audit logs, email notifications to repository administrators, and security tab alerts, ensuring complete visibility into security exceptions and enabling rapid incident response when legitimate secrets are inadvertently pushed.
GitHub Actions Push to Protected Branch: CI/CD Integration Challenges
Implementing GitHub Actions push to protected branch workflows requires careful consideration of how push protection interacts with automated CI/CD processes. GitHub Actions workflows often need to push commits containing generated content, version updates, or automated fixes, which can trigger push protection mechanisms if secrets are inadvertently included.
To allow GitHub Actions to push to protected branch configurations while maintaining security, organizations should implement service account tokens with minimal required permissions and configure branch protection rules that accommodate automated workflows. The GitHub protect branch from direct push settings should include exceptions for specific GitHub Actions workflows while maintaining push protection for human contributors.
Best practices include using GitHub's built-in GITHUB_TOKEN for automated pushes, implementing secret scanning in pre-commit hooks within Actions workflows, and configuring branch protection rules that require status checks from security scanning tools. This approach ensures that automated processes can function effectively while maintaining the security benefits of push protection, creating a robust defense-in-depth strategy that protects against both human error and automated secret exposure.
Conclusion
Although push protection is a great step towards securing open-source repositories, it's important to acknowledge the gaps that remain uncovered. It's crucial to avoid assuming complete protection against the vast attack surface on GitHub at the click of a button.
A multi-layered approach to security is always beneficial. We encourage combining push protection with pre-commit hook protection, such as installing ggshield. Additionally, history scanning is a separate field that requires Public Monitoring for proactive threat-hunting purposes. For a more comprehensive comparison between GitHub Advanced Security and GitGuardian's enterprise-level capabilities, see our detailed comparison page.
FAQ
What is GitHub push protection and how does it work?
GitHub push protection is a security feature that scans code for highly identifiable secrets before allowing commits to be pushed to public repositories. If a secret is detected, the push is blocked, and the developer receives remediation guidance. The feature is now enabled by default for public repositories, helping prevent accidental credential exposure at the source.
What are the main limitations of GitHub push protection?
GitHub push protection only detects a limited set of secret types with low false positive rates, lacks historical scanning capabilities, and is ineffective for private repositories made public. Additionally, it may miss generic secrets and can be bypassed by developers, potentially leaving gaps in your security posture.
How can organizations enable or configure GitHub push protection for private repositories?
For private repositories, push protection can be enabled at the repository, organization, or enterprise level via the "Code security and analysis" settings. Enterprise administrators can further customize which secret patterns are protected and integrate with GitHub Advanced Security for granular control, ensuring alignment with compliance and security requirements.
How does the push protection bypass mechanism impact security and compliance?
When developers bypass push protection, GitHub logs the event, generates alerts, and notifies repository administrators. Organizations can implement delegated bypass workflows requiring security reviewer approval. While this maintains development velocity, it also ensures visibility and auditability of exceptions, supporting incident response and compliance monitoring.
Does GitHub push protection scan historical commits or only new pushes?
GitHub push protection operates in real-time and does not scan historical commits. This means secrets already present in a repository’s history remain undetected. For comprehensive coverage, organizations should perform historical scans using dedicated tools to identify and remediate legacy exposures.
How should organizations handle CI/CD workflows that interact with protected branches?
To support CI/CD workflows, use service account tokens with minimal permissions and configure branch protection rules to allow specific GitHub Actions workflows. Employ pre-commit secret scanning in automated pipelines and require status checks from security tools to maintain robust defense while enabling automated pushes.
Why is a multi-layered secrets detection strategy recommended in addition to GitHub push protection?
Relying solely on GitHub push protection may leave gaps due to its limited detection scope and lack of historical scanning. A multi-layered approach—combining pre-commit hooks, historical scans, and broader secret detectors—ensures comprehensive coverage, reduces risk, and supports proactive incident response for modern development environments.
