Dotenvx

Status: Active
Last Updated: 2026-08-26
Category: Sysadmin / Secrets
Prerequisites: sysadmin.md, secrets.md
Tags: dotenvx, secrets, encryption, cli, forgejo-actions

Summary

Dotenvx layers encrypted .env files so secrets can live in Git safely while being decrypted at runtime via CLI commands or CI/CD actions. Migration from dotenv to @dotenvx/dotenvx is a single import change.

Context / Why This Matters

Without encryption, committing .env files leaks secrets; without layered files, local overrides and production configs compete. Dotenvx solves both by splitting encrypted artifacts from decryption keys and supporting multi-file stacks (dev, local, production).

Implementation / Core Content

Core Product Signals

• CLI wrapper: dotenvx run -- <command> injects decrypted env vars at runtime.
• Multi-environment stacking: override files (.env.local, .env.production) merge in order; agents can select contexts programmatically.
• Encryption model: AES-256 encrypted .env files committed to Git; decryption key lives in .env.keys or an external vault (Forgejo Secrets, Vault).

Tooling & Integrations

• vite-plugin-dotenvx: injects values at build time, regenerates .env.example, updates .gitignore, and keeps secrets encrypted at rest.
• Forgejo Actions can run dotenvx run --env-file=.env.production -- bun run deploy; encrypted production secrets stay in Git and are decrypted only in the CI environment.
• Ecosystem wrappers (e.g., Noundry.DotEnvX) confirm the broader adoption of AES-256 + validation patterns.

Operational Controls

• Separate read-only and write credentials inside Dotenvx; rotate them through Forgejo Actions that update encrypted .env.production and log audit events.
• Keep .env.keys out of version control; store it in a vault or CI secret store.
• Layered merging (defaults → host overrides → .env content → runtime env vars) provides traceable provenance for every variable.

Practical Examples

# Local development with local override
dotenvx run --env-file=.env.local -- bun run dev

# Production deploy in Forgejo Actions
- name: Deploy
  run: dotenvx run --env-file=.env.production -- bun run deploy
  env:
    DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_KEY }}

Common Pitfalls & Troubleshooting

Pitfall	Fix
.env.keys committed to repo	Add .env.keys to .gitignore and rotate the key
Decryption fails in CI	Verify DOTENV_PRIVATE_KEY_* is set as a Forgejo secret
Wrong layer applied	Confirm --env-file matches the environment; list layers with dotenvx get
Overwriting environment variables unexpectedly	Layer order: .env < .env.local < .env.production < runtime env

Next Steps / Ops Actions

1. Verify .env.keys rotation cadence is documented in sysadmin/secrets.md.
2. Map Dotenvx commands to Forgejo Actions in sysadmin/system-admin-basics.md.
3. Confirm encryption workflow is captured in sysadmin/secrets.md.

Sources & Related Articles

• Dotenvx docs (quickstart, CLI, layered environments).
• Vite plugin docs.
• Noundry DotEnvX wrapper (AES-256 + validation).
• Related KB: sysadmin.md, secrets.md, dotenvx.md (reference entry)

Change Log

2026-08-26

• Expanded from 2.7KB research log to production-quality article with full format, examples, and references.