secret-handling

name	secret-handling
description	Keep secrets out of source control, logs, and generated artifacts
domain	security
confidence	high
source	template

Context

Agents and contributors may encounter configuration files, workflow inputs, or environment variables that contain live credentials. Never copy those secrets into committed files, logs, or documentation.

Patterns

Safe inputs

• Prefer .env.example, .env.sample, or documented configuration schemas
• Ask for missing values instead of trying to discover secrets from local machine state
• Use secret stores and CI secret configuration for real credentials

Safe output

• Redact tokens, passwords, connection strings, and email addresses in generated artifacts
• Replace live values with placeholders such as <set in environment>
• Document required secret names without including their contents

Validation

Before committing, review changed files for:

• API keys or tokens
• Passwords or connection strings
• Private keys or certificates
• Personally identifying contact details that should not be published

Examples

✓ Good:

• GITHUB_TOKEN=<set in repository secrets>
• SMTP_PASSWORD=<set in environment>

✗ Poor:

• Copying a token into workflow YAML or Markdown
• Logging a full connection string for troubleshooting
• Reading a local .env file when a sample file would answer the question

Anti-patterns

• Treating secret files as documentation
• Committing redaction mistakes because generated files were not reviewed
• Reusing example credentials that look real