Background: The Nightmare of Losing Accounts Due to Secret Leaks
It only takes a 5-second accidental git push of a .env file containing an AWS Access Key to a public repo to see how fast hackers move. Within minutes, automated bots can cost you thousands of dollars by running crypto-mining scripts. Even with private repos, the habit of storing passwords in plain-text remains a ticking time bomb.
Many developers often use .gitignore to avoid this, but this approach makes team collaboration extremely frustrating. Every time a new member joins, the team has to manually pass config files around via Slack or Telegram — a process that is both manual and prone to loss. More importantly, even if you delete the file in the current commit, it remains permanently embedded in the Git history. Malicious actors just need to look back in time to retrieve everything.
That’s where Mozilla’s SOPS (Secrets Operation) shines. Instead of encrypting the entire file into an unreadable blob, SOPS only encrypts the values and keeps the keys intact. This allows you to still view the file structure and perform a smooth git diff without exposing actual data. This tool provides extensive support, from PGP to major players like AWS KMS, GCP KMS, and Azure Key Vault.
Installing SOPS: Fast, Simple, and Lightweight
Depending on your operating system, it takes less than a minute to set up SOPS on your local machine.
Quick Installation Commands
For Mac or Linux users (with Homebrew), use this command for speed:
brew install sopsOr if you want to download the Linux binary directly:
curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.linux.amd64
sudo mv sops-v3.8.1.linux.amd64 /usr/local/bin/sops
sudo chmod +x /usr/local/bin/sopsInitializing a PGP Key
For personal projects or small teams, PGP is the most cost-effective and efficient option. For large enterprises, prioritize KMS for centralized access management.
Generate a new GPG key pair with the command:
gpg --full-generate-keyChoose RSA 4096-bit to ensure the highest level of security available today. After creation, retrieve the key’s Fingerprint (unique identifier):
gpg --list-secret-keys --keyid-format LONGCopy the string of characters from the pub line (e.g., 1A2B3C4D...). This serves as the ID that tells SOPS which key to use.
Pro tip: Since you’re going through the effort of encryption, make sure the original password is high-quality. Instead of 123456, I often use the password generator at toolcraft.app/en/tools/security/password-generator. This tool runs entirely in the browser and is extremely secure when combined with SOPS for storage in config files.
Hands-on: Encrypting and Editing Files Directly
Suppose you have a secrets.yaml file containing sensitive information:
api_key: "sk_live_51Mz..."
db_password: "super-strong-pass-2024"
username: "admin"Step 1: Configuring the Rules with .sops.yaml
Don’t type the key ID manually every time you run a command; it’s exhausting! Create a .sops.yaml file in the project root:
creation_rules:
- path_regex: secrets\.yaml$
pgp: "YOUR_GPG_FINGERPRINT_HERE"Step 2: Encrypt with a Single Command
Run this command to transform your data into a “matrix”:
sops -e -i secrets.yamlOpen the file, and you’ll see api_key is still there, but the value behind it has become a long ENC[AES256_GCM,...] string. Perfectly safe to push to GitHub!
Step 3: Editing Without Decryption
This is the most “valuable” feature. You don’t need to decrypt to a temporary file (which is risky). Just type:
sops secrets.yamlSOPS will open the file in Vim/Nano. Simply edit the content and save (:wq); SOPS will automatically re-encrypt the new content immediately. It feels as smooth as editing a regular text file.
CI/CD Integration and Teamwork
To allow colleagues to decrypt as well, just add their Public Keys to the .sops.yaml file. Each file can have multiple “keys” simultaneously.
Integrating into GitHub Actions
In your deployment script, you need to load the Private Key into GitHub Secrets, then decrypt before the application starts:
# Decrypt the file for the app
sops -d secrets.yaml > secrets.decrypted.yamlCrucial Things to Remember
- Always check git diff: Before
git commit, make sure you see a jumble of characters instead of the old password. - Backup your Private Key: Losing the key means losing all secrets; there is no “forgot password” button. Store it in 1Password or print it out and keep it in a safe place.
- Don’t forget your colleagues: If you encrypt without adding the team’s keys, they will be looking at the file with total helplessness.
Implementing SOPS might take an extra 10-15 minutes of initial setup, but it provides absolute peace of mind. From now on, every time you git push, you can confidently go grab a coffee without worrying about leaking API keys. Good luck with your implementation!
