Concept · workflow · in production
git-crypt for .env Files
Committing `.env` files as encrypted source allows secure version control of application secrets, streamlining local development and deployment without out-of-band secret sharing.
`git-crypt` for `.env` files provides a robust, version-controlled mechanism to manage sensitive environment variables directly within a Git repository, ensuring they are encrypted at rest and only decrypted by authorized developers.
What it is
`git-crypt` is a Git extension that enables transparent encryption and decryption of files in a Git repository. When configured, specified files are encrypted when committed to the repository and decrypted automatically when checked out. For `.env` files, this means sensitive keys, API tokens, and database credentials can reside in the same repository as the application code, but in an encrypted state. Developers with the correct GPG key or symmetric key can decrypt these files locally, while the remote repository (e.g., GitHub) only stores the ciphertext. This approach treats secrets as first-class source code, subject to version control, commit history, and pull request reviews, rather than as an external, out-of-band concern.
Why it matters
Managing environment variables securely and efficiently is a persistent challenge for any team, especially in a portfolio with multiple distinct products. Traditionally, teams rely on `.env.example` files, requiring developers to manually populate secrets, or use dedicated secret management services. The former introduces friction during onboarding and risks inconsistencies, while the latter can add complexity and cost, particularly for a lean operation. `git-crypt` eliminates these trade-offs by allowing secrets to be versioned alongside code. This improves developer onboarding significantly; a new contributor can clone a repository and, after a one-time key setup, have all necessary `.env` files automatically decrypted. It also enhances security by ensuring secrets are never committed in plaintext and provides an audit trail for changes. For a portfolio like Total Ventures, where operational efficiency directly impacts Runway as Decision Frame, reducing setup overhead is critical. This method aligns well with the lean operational philosophy of Bootstrapped vs Funded projects, offering a secure and low-cost solution.
How TV applies it
At Total Ventures, every new project repository is initialized with `git-crypt` enabled for its `.env` files. We define a `.gitattributes` entry like `*.env filter=git-crypt diff=git-crypt` to ensure all `.env` files are automatically encrypted upon commit. Each developer, including myself, has a GPG key added to the `git-crypt` configuration for decryption. When working on projects that deploy to Vercel, for instance, the `.env` files contain local development variables, while production secrets are managed directly within Vercel's environment variables dashboard. This separation ensures that local development environments are easy to set up securely, without exposing production secrets in the repository. For backend services interacting with Firebase or using APIs like Resend, the API keys are stored in these encrypted `.env` files for local testing. This consistent approach across the portfolio means that whether I'm spinning up a new project or revisiting an older one, the secret management workflow is identical and reliable. The VERA Agent Daemon could potentially integrate with this by auditing `.gitattributes` files to ensure `git-crypt` is correctly applied across all repositories, maintaining a consistent security posture.
Common failure modes
The primary failure mode for `git-crypt` involves key management. If a developer loses their GPG key or if the key is not correctly added to the `git-crypt` configuration, they will be unable to decrypt the `.env` files, halting local development. Another common issue is forgetting to add the `*.env` pattern to `.gitattributes`, leading to plaintext secrets being committed, which defeats the entire purpose. Merge conflicts in `.env` files, while rare, can also be tricky to resolve when encrypted. It's crucial to establish a clear policy for adding new keys and rotating old ones. Regularly verifying the `.gitattributes` file and ensuring `git-crypt` status (e.g., `git crypt status`) confirms files are encrypted as expected are important maintenance steps.
FAQs
- How does this compare to using a dedicated secret manager like HashiCorp Vault?
- `git-crypt` is simpler for smaller teams and local development, integrating directly with Git. Vault offers more enterprise-grade features like dynamic secrets and auditing, which might be overkill for early-stage projects.
- What if I need different `.env` files for different environments (dev, staging, prod)?
- We commit encrypted `.env.development` and `.env.test` files. Production secrets are managed directly in deployment platforms like Vercel or Firebase, never committed to the repository.
- Is this secure enough for highly sensitive data?
- For local development and non-production environments, yes. For production secrets, dedicated platforms like Vercel's environment variables or cloud secret managers are generally preferred due to their robust access controls and auditing.
Want to see how Total Ventures applies this in production?
See the brand portfolio →