Format Atlas

Guides

Where to keep configuration and secrets

Separate ordinary settings from credentials, then choose a suitable place for local development, CI, and production based on access and exposure risk.

Which format should you choose?

Choose by the role each file plays in your workflow.

  • Shared defaults → Commit examples without secret values
  • Local developer settings → Use a local .env file when supported, and keep it out of Git
  • CI credentials → Use the CI provider's secret store and restrict access
  • Production and containers → Use the runtime platform's secret facility and grant access only where needed
  • A value may have leaked → Revoke or rotate it; deleting the file is not enough

Separate settings from secrets

Treat non-sensitive settings, such as service URLs and feature flags, differently from credentials such as passwords, API keys, and private keys. Do not hard-code real credentials or commit files containing them to a shared repository. First confirm which configuration mechanisms your application accepts.

Keep local .env files out of Git

When supported by your tools, keep each developer's local values in a .env file and share an .env.example containing variable names and placeholders only. Ignore the real .env file and verify it is not already tracked. A Git ignore rule is not secure storage and does not remove values from existing history.

Use CI secret stores with least privilege

In CI systems such as GitHub Actions, add credentials through the provider's secret facility rather than writing them into workflow files. Limit access to the repositories, environments, and jobs that need it; grant tokens only the required permissions; and avoid printing values. Log masking is not a guarantee that every transformed value or command output will be hidden.

Provide secrets from the production runtime

For production, prefer the hosting or cloud platform's secret store and limit which deployments and services can read each value. Docker Compose can mount secrets as files for explicitly authorized services; details and limitations vary by platform, so check the documentation for your actual runtime. Where supported, consider short-lived credentials such as OIDC instead of long-lived keys.

Revoke or rotate credentials after exposure

If a secret may have appeared in a commit, CI log, or chat, removing the visible copy is not enough. Revoke or rotate the affected key or token first, then review access logs and its possible use. Afterwards, address repository history and logs as appropriate and tighten access controls to prevent a repeat.

Formats to consider

.env

Good for: Loading local settings for tools that support .env files

Less suitable for: Sharing or storing secrets without protection

.gitignore

Good for: Preventing untracked local .env files from being added accidentally

Less suitable for: Revoking secrets or removing tracked values from Git history

Before you export

  • .env and .gitignore do not by themselves make secrets safe; check Git tracking, CI logs, backups, and the runtime secret store.
  • Secret masking may not hide transformed values or every command output.
  • If a credential may have leaked, revoke or rotate it rather than only deleting the file.

Guides

Choose a configuration file formatCheck which formats the target tool accepts first. If several are supported, choose one the team can validate and maintain safely.Choose a certificate or key file formatCheck the destination's required format first, and distinguish an issued certificate, a certificate request, and a private key.

References and specifications