Environment variables make applications configurable, while secrets protect credentials, tokens, certificates, and other sensitive values. This deployment guide provides a reusable CI/CD secrets management checklist for local development, pull requests, staging, and production, including safe injection, rotation, revocation, troubleshooting, and leakage prevention.
Overview
Environment variables and secrets are related but should not be managed identically. A non-sensitive setting such as LOG_LEVEL=info may be stored as ordinary configuration. A database password, API token, signing key, or private certificate should be treated as a secret throughout its lifecycle.
The safest workflow separates four concerns:
- Creation: Generate credentials with the smallest practical scope and an identifiable owner.
- Storage: Keep sensitive values in an approved secret store, CI/CD secret facility, or local file that is excluded from version control.
- Injection: Provide values only to the job, environment, service, or command that needs them.
- Rotation and revocation: Replace credentials on a planned schedule or after a suspected exposure, then remove the old value.
Do not assume that an environment variable is automatically secret. It can appear in process inspection, diagnostic output, crash reports, build artifacts, shell history, or logs depending on the operating system and tooling. Treat secret injection as a controlled handoff rather than as a convenient way to pass arbitrary configuration.
For deployment work, document which variables are required by each environment. A useful inventory records the variable name, purpose, owning team, source of truth, scope, rotation method, and whether the application can start without it. Never place the secret value itself in the inventory.
| Workflow | Appropriate storage | Primary control | Watch for |
|---|---|---|---|
| Local development | Ignored .env file or local secret manager | Keep values outside the repository and share only a safe example file | Accidental commits, copied production credentials, shell history |
| GitHub Actions | Repository, environment, or organization-level secrets and variables | Use environment protection and narrow workflow permissions | Pull request code, forked workflows, command output |
| GitLab CI | Project, group, or environment-scoped CI/CD variables | Use protected and masked settings where appropriate | Untrusted branches, debug traces, overly broad variable scope |
| Cloud secret manager | Provider-managed secret store accessed by workload identity | Grant the runtime only the specific secret paths it needs | Over-permissioned roles, unmanaged copies, failed identity bindings |
Checklist by scenario
Before adding a new integration
- Write down the exact capability required: read-only API access, deployment access, database access, or another operation.
- Choose a credential with the narrowest available permissions, limited resources, and an explicit owner.
- Decide where the value belongs in each environment. Local development, CI, staging, and production may use different credentials.
- Record the variable name and a non-sensitive description in the project documentation.
- Define how the credential will be rotated and revoked before using it in a pipeline.
- Add a placeholder to a safe example file such as
.env.example; never add the real value.
Local development
- Add
.env,.env.local, or the project-specific secret file to.gitignorebefore populating it. - Use a separate local credential rather than copying a production token.
- Validate required names and formats at application startup, but do not print values in validation errors.
- Provide documentation that explains where a developer obtains access without placing credentials in chat, tickets, or source files.
- Check shell scripts, task runners, IDE launch configurations, and container definitions for accidental value expansion.
Pull requests and preview environments
- Assume code from an untrusted branch could attempt to read any secret made available to its job.
- Do not expose production credentials to tests or preview deployments unless there is a documented, isolated reason.
- Use synthetic data, restricted service accounts, and short-lived credentials for previews.
- Review workflow changes with the same care as application code. A change to a workflow can alter who receives secrets.
- Keep deployment credentials out of jobs that only lint, test, or build public artifacts.
For a broader preview workflow, see Preview Environments for Pull Requests.
CI/CD deployment
- Separate build, test, and deploy jobs so only the deploy step receives deployment credentials.
- Use environment-specific secret names or scopes rather than one universal value for every stage.
- Grant the job only the permissions it needs. For cloud deployments, prefer workload identity or short-lived credentials when the platform supports them.
- Pass values through the CI system's supported secret mechanism, not through committed configuration files.
- Disable verbose shell tracing around commands that may expand sensitive variables.
- Prevent secrets from entering artifacts, caches, generated manifests, Docker image layers, and deployment logs.
- After deployment, verify the application using a health check that does not expose configuration or credentials.
# Illustrative pipeline pattern; adapt names and syntax to your CI provider
steps:
- name: Build
run: ./scripts/build.sh
- name: Deploy
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
TARGET_ENV: staging
run: ./scripts/deploy.shThe example demonstrates a principle, not a universal syntax: keep secret access close to the command that needs it, and avoid exporting the value globally for the entire pipeline.
Production rotation or suspected exposure
- Identify the credential, affected systems, exposure window, and likely access path.
- Revoke or disable the old credential first when continued access presents a risk.
- Create a replacement with equivalent or reduced permissions.
- Update the authoritative secret store and redeploy affected services.
- Confirm that the new value works, then remove old copies from CI variables, local files, caches, artifacts, and documentation.
- Review audit logs and deployment history where available.
- Document the event and improve the control that failed, such as scanning, permissions, review, or rotation ownership.
For related deployment failures involving secrets, artifacts, and rollbacks, use the CI/CD Deployment Troubleshooting Matrix.
What to double-check
Secret inventory worksheet
Keep this table in an access-controlled location. It should describe secrets without containing their values.
| Field | Example entry |
|---|---|
| Variable name | PAYMENTS_API_TOKEN |
| Purpose | Allows the billing worker to submit payment events |
| Environment | Staging only, production separate |
| Owner | Platform team or named service owner |
| Storage | CI environment secret or cloud secret manager |
| Scope | One repository, service, account, or resource group |
| Rotation method | Provider console, API, or scheduled automation |
| Last review | Date and reviewer, not the secret value |
Pipeline review
- Are secrets available only to the jobs and environments that require them?
- Can code from forks, untrusted branches, or external contributors reach a privileged job?
- Are environment approvals or equivalent controls used for production deployment?
- Could a failed command print the complete environment or a constructed URL containing a token?
- Are masking rules reliable for the value's actual representation, including encoded or transformed forms?
- Do Dockerfiles, image layers, build caches, generated files, and artifacts contain credentials?
- Does the deployment use the intended environment, account, region, and secret version?
Troubleshooting table
| Symptom | Likely checks | Safe next step |
|---|---|---|
| Variable is empty | Name mismatch, wrong job scope, unavailable environment secret, or conditional workflow path | Log the variable name and presence status, never its value; verify scope and spelling |
| Staging uses production settings | Shared variable, fallback value, incorrect environment mapping, or stale deployment configuration | Separate names and scopes, then inspect the resolved non-secret configuration |
| Masking fails | Value was transformed, split, encoded, or printed as part of a larger diagnostic object | Stop the job, remove the output, rotate the credential, and tighten logging |
| Deployment suddenly cannot authenticate | Credential expired, was revoked, rotated without redeploying, or lacks required permissions | Check identity and audit records, issue a replacement if needed, and redeploy deliberately |
| Secret scanner reports a finding | Credential may exist in source, history, an artifact, or a build cache | Treat it as exposed until verified otherwise; revoke, investigate, and clean affected locations |
Common mistakes
- Committing a real
.envfile: Adding it to.gitignorelater does not remove values from repository history or existing clones. Revoke exposed credentials and remove the data through an appropriate history-cleaning process. - Using one credential everywhere: A shared production token increases blast radius and makes ownership and investigation harder. Separate credentials by environment and service where practical.
- Printing configuration while debugging: Commands that dump the entire environment can leak more than the failing variable. Print names, boolean presence checks, and safe metadata instead.
- Assuming masking is complete protection: Masking reduces accidental log exposure but does not prevent a compromised job from using a credential. Restrict access first.
- Passing secrets through command-line arguments: Arguments may be visible to process inspection or recorded by tooling. Prefer the CI provider's environment or file-based secret mechanism, with careful cleanup.
- Placing secrets in container image layers: Removing a file in a later Docker layer may leave it in earlier layers. Inject credentials at runtime or use the platform's supported secret mechanism.
- Rotating without testing the consumer: Rotation can cause an outage if the application caches the old value or multiple services use an undocumented copy. Plan a controlled replacement and verification sequence.
When a deployment also changes DNS or TLS configuration, keep those changes observable and reversible. The related ACME certificate renewal guide and DNS runbook provide useful adjacent checklists.
When to revisit
Review this checklist before each new service integration, repository handoff, production migration, credential rotation, or major CI/CD workflow change. It is also worth revisiting before seasonal planning cycles and after changes to repository permissions, deployment environments, cloud identities, secret-manager integrations, or artifact handling.
At a minimum, schedule a recurring inventory review. Confirm that every listed secret has an owner, a defined scope, a known rotation path, and a current consumer. Remove unused variables and revoke credentials belonging to retired services or former deployment paths. Test the recovery process with a non-production credential so the team knows how to replace a value without improvising during an incident.
Use this final action list:
- List every secret used by local development, CI, staging, and production.
- Mark each value as owned, scoped, stored, and rotatable.
- Remove secrets from source, logs, artifacts, images, and caches wherever possible.
- Test a controlled rotation in staging.
- Review privileged workflow changes and production approvals.
- Record the next review date and the person responsible for it.
Secrets management is not a one-time setup task. It is a deployment control that should evolve whenever the code, pipeline, hosting platform, or access model changes.