Have you ever accidentally committed an API key, database password, or access token to Git? 😬
A single mistake can expose sensitive credentials in a repository. Even if you remove the secret in the next commit, it may remain in Git history, forks, clones, or CI/CD logs.
Gitleaks is an open-source secret-scanning tool that helps developers detect potentially exposed credentials in Git repositories and files.
In this article, we'll explore how Gitleaks works, how to install it on Ubuntu, its pros and cons, real-world applications, and how to integrate it into a GitLab CI/CD pipeline.
🚀 1. What Is Gitleaks?
Gitleaks scans source code and Git history for patterns that resemble sensitive information, including:
- API keys and access tokens
- Database credentials
- Cloud provider secrets
- Private keys
- Hardcoded passwords
- Other credential patterns covered by its detection rules
It helps teams introduce automated secret scanning into their development workflows.
The goal is simple: detect secrets as early as possible before they become a security incident.
Gitleaks is not a complete security scanner. It focuses on exposed secrets rather than vulnerabilities such as SQL injection, insecure authorization, or outdated dependencies.
Official repository: https://github.com/gitleaks/gitleaks
⚙️ 2. How Does Gitleaks Work?
A typical workflow looks like this:
- A developer writes code containing a potential secret.
- Gitleaks scans the repository or files.
- The scanner reports potential findings.
- The developer investigates and remediates genuine exposures.
- CI/CD can fail the pipeline if the configured scan detects a secret.
For example, consider this Python file:
# config.py — fake example values
API_KEY = "example_placeholder_key"
DATABASE_PASSWORD = "fake_password_for_demo"
Gitleaks may detect these values depending on its rules and configuration. Detection is not guaranteed for every credential format.
📦 3. Install Gitleaks on Ubuntu
Download the appropriate Linux archive from the official releases page:
https://github.com/gitleaks/gitleaks/releases
After downloading the archive matching your system architecture, extract and install the binary:
tar -xzf gitleaks_*.tar.gz
sudo install -m 755 gitleaks /usr/local/bin/gitleaks
Verify the installation:
gitleaks version
Note: Archive names vary by release and architecture. Adjust the extraction command to match your downloaded file.
🔍 4. Scan Your Git Repository
Navigate to your project directory:
cd /path/to/your/project
Scan the Git repository:
gitleaks git .
Scan files in a directory:
gitleaks dir .
Check the options supported by your installed version:
gitleaks git --help
gitleaks dir --help
Gitleaks can report matching findings and return a non-zero exit status when secrets are detected. This behavior makes it useful in automated CI/CD pipelines.
Important: Treat scan output as sensitive because reports may contain information about exposed credentials.
💀 5. Real-World Example: Accidentally Committed Credentials
Imagine a developer commits this configuration file:
# database.py
DB_HOST = "db.example.internal"
DB_USER = "app_user"
DB_PASSWORD = "fake_demo_password"
The developer later removes the password from the file and pushes another commit.
Is the secret gone?
Not necessarily. The earlier commit may still contain it.
Scan the repository:
gitleaks git .
If a real credential has been exposed:
- Revoke or rotate it immediately.
- Investigate possible unauthorized access.
- Remove the hardcoded credential from the source code.
- Review Git history, forks, clones, and CI/CD logs.
- Rewrite Git history if necessary and coordinate with your team.
Deleting a secret from the latest commit does not invalidate the credential. Rotation or revocation is the critical first step.
🛡️ 6. Integrate Gitleaks into Your Git Workflow
Option A: Pre-commit scanning
Running secret scans before commits provides developers with immediate feedback.
Some older tutorials use this command:
gitleaks protect --staged
This is version-dependent and should not be assumed to work with current releases.
Check your installed version's documentation and configure a compatible Git hook or pre-commit integration.
Repository: https://github.com/gitleaks/gitleaks
Local hooks are useful, but they can be bypassed. Use CI/CD scanning as an additional enforcement layer.
Option B: GitLab CI/CD integration
Create or update your .gitlab-ci.yml file:
stages:
- security
gitleaks_scan:
stage: security
image: zricethezav/gitleaks:<PINNED_VERSION>
script:
- gitleaks git .
Replace <PINNED_VERSION> with a valid release tag available in the container registry.
This job runs Gitleaks during the security stage. If the scan returns a failure status, the job fails and can prevent the pipeline from passing.
For production environments:
- Pin the image to a verified version or digest.
- Restrict access to logs and reports.
- Avoid printing actual credentials in CI output.
- Review exclusions and allowlists carefully.
- Test the job before making it a required pipeline check.
- Include historical scanning where appropriate.
📊 7. Pros and Cons of Gitleaks
✅ Pros
1. Open-source
Gitleaks is freely available and can be used by individual developers and organizations.
2. Easy CI/CD integration
It works well with automated pipelines and developer tooling.
3. Git history scanning
It can identify potential secrets in historical commits, not just the current version of a file.
4. Fast feedback
Developers can catch mistakes before code is merged or published.
5. Customizable rules
Detection rules and exclusions can be adapted to repository-specific requirements.
6. Useful for DevSecOps
It adds an automated security check to existing development workflows.
❌ Cons
1. False positives
Some legitimate strings may match detection rules and require manual investigation.
2. False negatives
Unusual formats, unsupported patterns, and certain encoded secrets may not be detected.
3. Not a secrets manager
Gitleaks detects potential exposures; it does not securely store or rotate credentials.
4. Historical exposure remains a risk
Finding a secret does not undo previous exposure. Credential rotation and incident investigation may still be necessary.
5. Large repositories can take longer to scan
Extensive Git histories can increase scan duration and CI resource consumption.
6. Configuration requires maintenance
Rules, allowlists, and exclusions must be reviewed to avoid missing genuine security issues.
🎯 8. Where Is Gitleaks Applicable?
| Use case | Application |
|---|---|
| Application development | Detect hardcoded API keys and passwords |
| DevOps | Scan configuration files and infrastructure code |
| GitLab CI/CD | Fail pipelines when configured scans detect secrets |
| GitHub repositories | Scan code and Git history before publishing |
| Kubernetes | Identify potential credentials in manifests |
| Microservices | Detect accidentally committed service tokens |
| Open-source projects | Reduce accidental exposure of credentials |
| Security audits | Identify potential historical secret leaks |
Gitleaks is especially useful when development teams manage application code, infrastructure, and deployment configuration through Git.
🔄 9. Gitleaks vs. Secrets Managers
Gitleaks and secrets managers solve different problems.
| Feature | Gitleaks | Secrets manager |
|---|---|---|
| Detect potential secrets in code | Yes | Not its primary purpose |
| Securely store credentials | No | Yes |
| Rotate or revoke credentials | No | Often supported through integrations |
| Integrate with CI/CD | Yes | Yes |
| Guarantee that no secret leaks | No | No |
Examples of secrets-management solutions include:
- HashiCorp Vault
- AWS Secrets Manager
- Azure Key Vault
A strong security architecture combines secret detection with secure credential storage.
For example, Gitleaks can flag a hardcoded database password, while the application retrieves its actual credentials from an approved secrets manager.
🧰 10. Best Practices
Follow these practices to make secret scanning more effective:
- Never hardcode credentials in application code.
- Scan early using developer hooks and CI/CD pipelines.
- Scan Git history to identify potential historical exposure.
- Rotate exposed credentials immediately.
- Apply least privilege to tokens and service accounts.
- Protect scan reports because they may contain sensitive information.
- Review allowlists instead of blindly ignoring findings.
- Pin scanner versions for reproducible CI/CD builds.
- Combine security controls such as dependency scanning, static analysis, and infrastructure security checks.
🏁 Conclusion
Gitleaks is a practical tool for detecting potentially exposed credentials in Git repositories. Its main advantage is that it can be integrated into existing developer workflows and CI/CD pipelines with relatively little operational overhead.
However, no secret scanner can guarantee that every credential will be detected.
The best approach combines automated secret scanning, secure credential management, least-privilege access, and a clear incident-response process.
My recommendation: Start by scanning an existing repository, review the findings, and integrate Gitleaks into your GitLab CI/CD pipeline. Once the rules and exceptions are understood, make the security job a required check.
Catching a credential before it reaches a shared repository is much easier than responding to a credential leak after exposure.
📚 References
- Gitleaks repository: https://github.com/gitleaks/gitleaks
- Gitleaks documentation: https://github.com/gitleaks/gitleaks#readme
- GitLab CI/CD documentation: https://docs.gitlab.com/ci/
Top comments (0)