Secrets management in code: the definitive guide for development teams

Why secrets in code are a critical risk

Hardcoded credentials are behind some of the largest data breaches on record. A git repository stores the entire commit history: even if a developer deletes an API key in a later commit, it remains accessible to anyone with access to the history — and repositories that were once public may have been cloned or indexed by monitoring tools before they were made private.

The risk is not limited to GitHub. CI/CD logs frequently print entire environment variables when a configuration error occurs. Docker images built with ARG or ENV that receive secrets write them into every layer of the image, available to anyone who runs docker history. Accidentally committed .env files account for a significant share of the exposure incidents reported on Have I Been Pwned and cataloged by OWASP.

The OWASP Top 10 lists Security Misconfiguration and Cryptographic Failures as high-impact vectors, and secret exposure maps directly into both categories. NIST SP 800-204C reinforces that credentials with indefinite validity and no rotation are a systemic risk, not just a one-off one. For a startup with a small development team and a fast deploy cadence, a single exposed production token can mean anything from the complete destruction of cloud infrastructure to the leak of every customer's data.

Secrets vaults: the correct architecture

The approach recommended by NIST and the DevSecOps community is to centralize all secrets in a dedicated vault and never let them reside in versioned files or environment variables configured by hand on servers. The leading options are HashiCorp Vault (open source, self-hosted or HCP), AWS Secrets Manager (managed, with native IAM integration and automatic rotation), and Doppler (a SaaS aimed at development teams, with environment sync and CI/CD integrations).

The correct flow is: the application authenticates to the vault using a workload identity (not a fixed password), obtains the secret with a defined scope and lifetime, and uses it in memory without ever writing it to disk or a log. In Kubernetes environments, this translates to the External Secrets Operator or the AWS Secrets and Configuration Provider (ASCP), which mount secrets as ephemeral volumes. In serverless functions such as AWS Lambda, the AWS SDK lets you fetch the secret at cold start and cache it in the instance's memory.

Doppler simplifies this flow for smaller teams: a CLI injects the correct variables for each environment (dev, staging, production) without the developer having to create local .env files. The developer runs doppler run -- npm start and the process receives the secrets as environment variables without them ever touching the file system. This eliminates an entire class of accidents.

Day-to-day best practices for the development team

The first control is .gitignore: every repository should ignore .env, .env.local, .env.*.local, *.pem, *.key, credentials.json, and any file that might contain credentials. GitHub provides per-language .gitignore templates that include these patterns, but the team should review them and add project-specific patterns. The .gitignore file is not sufficient on its own — a developer can force a commit with git add -f — which is why it is the first line of defense, not the only one.

Pre-commit hooks with gitleaks or detect-secrets add an automatic layer: before each commit, the hook scans the diffs for credential patterns (AWS keys, GitHub tokens, JWTs, connection strings) and blocks the commit if it finds anything suspicious. Installation is simple via the pre-commit framework, and the team can share the configuration in the repository. GitHub also offers push protection natively for repositories with GitHub Advanced Security, blocking pushes that contain secrets detected by its ML models.

Least privilege is the principle that limits the blast radius. Each service should have credentials with the minimum permissions needed for its function — a Lambda function that only reads from an S3 bucket does not need permissions for EC2 or RDS. API tokens should be tightly scoped (read vs. write, a specific resource). Periodic rotation — recommended every 90 days or after any team change — ensures that old credentials are invalidated even if they leaked without anyone's knowledge.

What to do when a credential leaks

The first action, before any investigation, is to revoke and rotate. Disable the token or key immediately at the provider — AWS Console, GitHub Settings, Stripe Dashboard, wherever it lives. There is no time to lose trying to understand the impact before removing access: the exploitation window can be minutes. Document the exact time of revocation for the incident timeline.

The next step is to audit usage. AWS CloudTrail access logs, GitHub API logs, database authentication logs — any record of the compromised credential's use should be collected and analyzed. The goal is to determine whether anyone used it in an unauthorized way, which resources were accessed, and whether data was exfiltrated. This analysis determines whether the incident is limited to the credential or whether there is a reportable data breach.

Deleting the commit does not fix it. Git history can be rewritten with git filter-repo (which replaces the older git filter-branch), but this requires a force-push across all branches and does not guarantee that earlier clones did not preserve the history. Platforms like GitHub may have cached the old version. The only action that matters is immediate revocation — cleaning up history is a complementary hygiene measure, not a security solution. NIST SP 800-61 places containment before eradication for exactly this reason.

Secrets in CI/CD pipelines and containers

CI/CD pipelines are high-risk vectors because they run code with production credentials in shared environments. GitHub Actions, GitLab CI, and CircleCI offer native encrypted secret storage that is injected as environment variables only during job execution — they never appear in logs (the value is masked automatically) and are not accessible to forks of public repositories. Never use the YAML env: section for hardcoded values; always use secret references such as ${{ secrets.API_KEY }}.

In Dockerfiles, the ARG instruction should never receive secrets — the value is written into the image's intermediate layers and is visible via docker history. The correct approach is to use BuildKit with --secret, which mounts the secret as a temporary file accessible only during the build and does not persist in any layer. For runtime secrets inside containers, the best practice is to inject them via environment variables in the task definition (ECS task definition, Kubernetes secret, Helm values) referencing the secrets vault — never copying the value into the image.

trufflehog can be integrated into the pipeline as a verification step: it scans the entire repository history and the artifacts produced by the build for known credentials, including secrets that may have slipped past the pre-commit controls. This scan should run on every pull request and block the merge when it finds any occurrences. Combining pre-commit hooks on the developer's machine with scanning in the pipeline creates a layered defense that covers the cases where a hook was skipped or bypassed.

AppSec and DevSecOps for startups: from solo founder to enterprise

Secrets management is one of the fundamental AppSec practices Decripte implements for development teams of all sizes — from startups at the product stage to companies with more than 100,000 employees. The process begins with an exposure assessment: scanning the git history, analyzing Docker images, reviewing pipelines, and mapping every credential in use and its permission scope.

Decripte offers a free Threat Management plan that includes monitoring for credential and company-data exposure on the dark web — a practical way to understand your risk level before investing in controls. For teams that need a full DevSecOps implementation — secret scanning integration, vault setup, rotation policies, and training for the development team — the paid plans cover everything from automation to incident response when a credential leaks.

Practical checklist

1. 1

   1. Install a secret-scanning pre-commit hook

   Add gitleaks or detect-secrets to your repository via the pre-commit framework. Create a .pre-commit-config.yaml file at the project root referencing the hook and run pre-commit install to enable it locally. Share the configuration in the repository so the whole team uses the same scanning.

2. 2

   2. Audit git history for existing credentials

   Run trufflehog git file://. or gitleaks detect --source=. to scan the entire repository history. Identify each credential found, revoke it immediately at the provider, and document the finding. Do not try to delete first — revoke first.

3. 3

   3. Set up a secrets vault for the production environment

   Choose between AWS Secrets Manager, HashiCorp Vault, or Doppler based on your team's size and infrastructure. Migrate all production credentials into the vault and update the application to fetch them at runtime via SDK or CLI — never via a versioned .env file.

4. 4

   4. Update .gitignore and remove versioned .env files

   Add .env, .env.*, *.key, *.pem, and credentials.json to .gitignore. If any of these files are already versioned, remove them with git rm --cached and force a new commit. Verify that the file does not appear in any active branch before continuing.

5. 5

   5. Enable GitHub push protection and configure CI/CD secrets

   In GitHub, enable Secret scanning and push protection under Settings > Code security. In the pipeline (GitHub Actions, GitLab CI, etc.), move all credentials into the CI/CD's native secret storage and replace hardcoded values with references to secret variables. Verify that no sensitive value appears in the execution logs.

6. 6

   6. Deploy automatic rotation and least-privilege policies

   Configure automatic rotation in AWS Secrets Manager (natively supported for RDS, Redshift, and managed secrets) or define a manual process with a documented calendar. Review each credential's permissions and reduce them to the minimum needed for the service's function — unused keys should be revoked immediately.

7. 7

   7. Establish a credential-leak response runbook

   Document the process: revoke at the provider, collect usage logs, determine impact, clean up history if needed, issue a new credential with a revised scope, and record the incident. Test the runbook in a tabletop exercise before a real incident occurs — the speed of your response in the first few minutes defines the scale of the damage.

Frequently asked questions