Secrets with git-secret

Store encrypted secrets in your repo. Zippy decrypts them automatically before each build.

Overview

Zippy integrates with git-secret to decrypt files before your build runs. This lets you safely commit encrypted API keys, credentials, and config files directly to your repository.

The workflow is simple: you add Zippy's GPG public key to your repo, encrypt your secrets, and push. Zippy handles the rest.

How it works

build output

$ git push zippy main

⚡ zippy → cloning code...

⚡ zippy → decrypting secrets...

⚡ zippy → success secrets decrypted

⚡ zippy → running zippy.sh

When Zippy detects a .gitsecret/ directory in your repo, it automatically runs git secret reveal before executing your build script.

Setup

Install git-secret

Install git-secret on your local machine:

# macOS

$ brew install git-secret

# Ubuntu/Debian

$ apt-get install git-secret

Initialize git-secret in your repo

$ cd your-project

$ git secret init

Add Zippy's GPG key

Download Zippy's public GPG key and add it to your keyring:

$ curl -sL https://zippy.sh/zippy.pub | gpg --import

$ git secret tell info@zippy.sh

This authorizes Zippy to decrypt your secrets during builds.

Add yourself as an authorized user

You'll also need to authorize yourself so you can encrypt/decrypt locally:

$ git secret tell your-email@example.com

Add and encrypt secret files

Add files to git-secret, then encrypt them:

# Add a secret file

$ git secret add .env

# Encrypt all secret files

$ git secret hide

This creates encrypted .env.secret files that are safe to commit.

Commit and push

$ git add .gitsecret/ .env.secret

$ git commit -m "Add encrypted secrets"

$ git push zippy main

Best practices

Add unencrypted files to .gitignore

git-secret adds them automatically, but double-check that .env and other secret files are in your .gitignore.

Re-encrypt after adding team members

When you add a new person with git secret tell, run git secret hide again to re-encrypt with the new key.

Use environment-specific files

Consider separate files like .env.production and .env.staging for different environments.

Troubleshooting

"git-secret reveal failed"

The decryption failed. Common causes:

Zippy's GPG key wasn't added with git secret tell info@zippy.sh
Secrets weren't re-encrypted after adding Zippy's key (run git secret hide)
The .gitsecret/ directory is incomplete or corrupted

What gets decrypted

Zippy decrypts all files tracked by git-secret before your build runs. The decrypted files are available in your working directory when zippy.sh executes.

Note: Decrypted secrets are only available during the build. They're never logged or persisted after the build completes.