cottage 0.2.1

A modern git based age-encrypted secrets manager for teams.

cottage

Cottage is a tool for teams to manage age-encrypted secrets in git repositories.

It provides a simple workflow to encrypt/decrypt secrets, manage recipients, and keep secrets out of the repo while still allowing for easy sharing via VCS. Cottage also generates redacted previews of encrypted secrets for better visibility and supports both persistent and temporary decryption workflows, while ensuring secrets are never committed in plaintext.

Features

• Exposure safe: Uses Rust's type system to make sure bugs can neven accidentally expose secrets.
• Team-friendly: Share public keys (recipients) in the repo, keep private keys (identities) local.
• Manages .gitignore: Automatically updates .gitignore to keep unencrypted secrets out of the repo.
• Previews: Generates timestamped redacted previews of encrypted secrets for better visibility.
• Rich diffs: Keeps git diff clean & reviewable, while ctg diff shows diff of locally modified secrets with tracked encrypted counterparts.
• Checksum verification: Prevents tampering and makes sure that the changes in secrets and recipients are correct and intentional.
• Persistent secrets workflow: ctg decrypt/edit/sync keeps decrypted secrets on disk.
• Temporary secrets workflow: ctg run (shortcut ctgx) decrypts secrets temporarily to run a command, then deletes them regardless of the command's success or failure.
• Clean up: ctg clean deletes all decrypted secrets from local repo to let you run your AI agents with a tiny bit less worry.
• Supports jj and non-git directories: ctg init turns any directory into a secret store.

Installation

# rust cargo-binstall
cargo binstall --locked cottage

# rust cargo
cargo install --locked cottage

# python pip
pip install cottage

# python uv
uv pip install cottage

Quick Start

Init project:

mkdir project && cd project

git init  # Optional, cottage works better with git but it's not required
ctg init  # Also optional in a git repo, required in a non-git directory

tree -a
# .
# ├── .cottage/           <- Auto-generated by `ctg init`
# │   ├── identity        <- Your private key, keep if safe. Move it to `~/.config/cottage/identity` to use it globally, or replace it with a soft link to one of your existing private key.
# │   └── recipients/     <- This is where your team keeps the public keys of all the recipients.
# │       └── sayanarijit <- Your public key. Commit it. To use an existing public key, just copy (don't softlink) that key here.
# ├── .git/...
# ├── .gitattributes      <- Added `*.cott.age binary filter=cottage-encrypted` to avoid polluting git diff
# └── .gitignore          <- Added `/.cottage/identity` for obvious reasons

Create or edit a secret.

ctg edit secret.yml --clean    # Opens secret.yml in $EDITOR
ctg encrypt secret.yml --clean # Another way to encrypt secrets
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml
#    edit .gitignore
# delete secret.yml

Run a command with temporary decrypted secrets:

cat secret.yml
# cat: secret.yml: No such file or directory

ctg run kubectl apply -f secret.yml          # decrypts secret.yml.cott.age to secret.yml
ctg run kubectl apply -f secret.yml.cott.age # same as above
ctg run kubectl apply -f .                   # decrypts all .cott.age files in .
ctg run ./deploy.sh                          # decrypts all .cott.age files in repo.

cat secret.yml
# cat: secret.yml: No such file or directory

Or use the shortcut:

ctgx ./deploy.sh  # same as ctg run -- ./deploy.sh

Sharing with a team member

To share your secrets, just push to git repo.

git add .
git commit -m "Add secret.yml"
git push origin main

Although, currently you are the only recipient. Ask your teammates to add their public keys to .cottage/recipients and push the changes. So that you can pull and re-encrypt the secrets for them.

git pull origin main

ctg sync  # or `ctg decrypt && ctg encrypt`
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # optional
# delete secret.yml

# review changes, commit and push
git add .
git commit -m "Add new recipient to secrets"
git push origin main

Now your teammates can pull the latest changes and decrypt secrets for themselves.

git hooks

You can use prek or pre-commit to set up git hooks to automatically check/encrypt secrets before commit and decrypt them after checkout.

See the example prek configuration here.

Learn More

See examples directory for more usage examples.

Troubleshooting

# See debug logs with -v, -vv or -vvv
ctg run -vvv -- ./deploy.sh

Roadmap

• Core functionality: encrypting, decrypting, managing recipients, diffing and syncing secrets.
• Nice to have features: shell autocompletions, gitignore, redacted previews, rich diffs, checksum verification and ctgx.
• Syncing remote secret vaults ctg pull and ctg push.
• ACL for more fine-grained access control.
• Audit logs of who accessed secrets and when.
• Secret rotation and expiration policies.
• Integrations with popular CI/CD tools and secret management platforms.
• Editor plugins for VSCode, JetBrains IDEs, Vim and Emacs.
• Docker images and kubernetes operators for easier integration with existing workflows.

License

MIT OR Apache-2.0