Secrets Management with Git-Crypt

This skill provides a secure, structured workflow for managing repository secrets (e.g. .env, *.tfvars, sec.json, settings.json) using git-crypt. It guides the agent to ensure sensitive credentials are never checked in as plaintext, instead maintaining parallel encrypted .enc versions checked into Git.

Table of Contents

• Triggers
• Prerequisites
• Secrets Setup and Sync Workflow
• Command Reference
• Verification Loop

Triggers

This skill MUST trigger whenever:

• The user mentions git-crypt, encryption, decryption, or secrets management.
• The user requests to store sensitive files (like .env, *.tfvars, settings.json, keyfiles) in the repository.
• The user attempts to commit or push files that should be encrypted (e.g. .env, *.tfvars, sec.json) to the repository.
• Cloning an existing repository that contains .enc files (e.g. .env.enc, terraform.tfvars.enc, settings.json.enc), indicating it was previously protected by git-crypt.
• Initializing a new repository and setting up local/remote secret configurations.
• Changing or adding secrets credentials that need to be committed securely.

Prerequisites

• Host Environment: Unix-like operating system (e.g., Linux, WSL, macOS).
• Git: A git repository must be initialized in the current project.
• git-crypt: The git-crypt command-line utility must be installed.
  • If missing, the helper script can attempt installation via sudo apt-get install git-crypt on Debian/Ubuntu systems.
• Helper Script: Make sure the helper script at skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh is executable (chmod +x).

Secrets Setup and Sync Workflow

Copy this checklist and track your progress:

Secrets Management Progress:
- [ ] Step 1: Verify git-crypt installation
- [ ] Step 2: Initialize or unlock the repository
- [ ] Step 3: Configure tracking and gitignore rules
- [ ] Step 4: Perform file synchronization
- [ ] Step 5: Verify environment security

Step 1: Pre-implementation safety & binary verification

Before attempting any encryption, decryption, or secret sync operations:

1. Verify Git Work Tree:
   • Confirm working directory is inside a Git repository (git rev-parse --is-inside-work-tree). If not in a Git repository, halt execution and prompt the user to run git init first.
2. Verify git-crypt Binary, Helper Script & Pre-Edit Sync State (MANDATORY BEFORE EDITING):
   • Ensure the helper script at skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh is executable (chmod +x).
   • CRITICAL PRE-EDIT RULE: Before modifying any local plaintext secret file (e.g. .env, mcp_config.json, *.tfvars), you MUST run status (and sync-from-enc if .enc is newer) first:

     ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh status

     Why this matters: If <file>.enc was updated upstream (e.g. via git pull) while the local git-ignored <file> is still an older copy, editing the stale <file> first updates its mtime to "now" and causes sync-to-enc to reintroduce deleted lines back into <file>.enc. Always reconcile <file> from <file>.enc (sync-from-enc) before applying edits.
   • If git-crypt is missing, offer to install it via:

     ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh install

Step 2: Unlock with an existing shared key (preferred) or initialize a new key

• CRITICAL KEY REUSE RULE: Always check whether the user already has a shared git-crypt symmetric key (e.g. ~/localdev/git-crypt-key, ../git-crypt-key, or $GIT_CRYPT_KEY_PATH) before ever running init, even on a brand-new repository!
  • git-crypt unlock <key_path> works on both cloned repositories and brand-new repositories (once .gitattributes is committed on a clean working tree) to bind the repository to your existing shared key without generating a new key.
  • If a shared key exists (or if unlock is run without arguments when ../git-crypt-key or ~/localdev/git-crypt-key is present), run:

    ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh unlock ~/localdev/git-crypt-key

• Only if no shared key exists AND the user explicitly wants to mint a brand-new key: Decide where the secure key will be stored outside of the repository (e.g., ~/secure-keys/my-project.key) and run:

  ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh init ~/secure-keys/my-project.key

  (Note: init will refuse to generate a new key if an existing shared key is detected at ../git-crypt-key or ~/localdev/git-crypt-key unless --force is passed.) Ensure the key is NEVER committed to git.

Step 3: Configure tracking and gitignore rules

Verify that .gitattributes in the root of the project contains the filter declaration:

*.enc filter=git-crypt diff=git-crypt

All unencrypted files (e.g. .env, settings.json, variables.tfvars) MUST be explicitly added to .gitignore. Running the helper script sync commands automatically appends them, but you must double-check that they are not tracked as plaintext in Git.

Step 4: Perform file synchronization

• Sync to encrypted versions (before committing changes): Copy unencrypted local files to their parallel .enc versions:
  • For a specific file:

    ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh sync-to-enc .env

  • For all known .enc files in the repository:

    ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh sync-to-enc

• Sync from encrypted versions (after unlocking a cloned repository): Restore all unencrypted plaintext files from the unlocked .enc versions:

  ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh sync-from-enc

Step 5: Verify environment security

Perform the steps in the Verification Loop before concluding your turn to make sure no plaintext secrets have been staged or committed.

Command Reference

The helper script supports the following commands:

Verification Loop

Before concluding the secrets setup or modifications, the agent MUST execute the following verification steps:

1. Execute Status Check

Run the helper status command:

./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh status

Ensure all parallel secret files report [OK]. If any say DO NOT MATCH, run the appropriate sync-to-enc or sync-from-enc command.

2. Verify gitignore Integrity

Confirm the unencrypted plain files are NOT tracked by Git. Run:

git ls-files --error-unmatch .env 2>/dev/null

• If the command returns output (file is tracked): IMMEDIATELY run git rm --cached <file> to remove it from staging while keeping it locally on disk.

3. Verify .gitattributes Structure

Verify that .gitattributes has:

*.enc filter=git-crypt diff=git-crypt

This ensures git-crypt transparently manages all .enc files under Git.

4. Git Crypt Status Check

Verify that git-crypt matches the filter correctly on staged/committed .enc files:

git-crypt status

The output must show that the .enc files are encrypted.