secrets-with-git-crypt

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:

   • Ensure the helper script at skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh is executable (chmod +x).
   • Run the status command of the helper script to check if git-crypt is installed and functioning:

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

   • If git-crypt is missing, offer to install it via:

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

Step 2: Initialize or unlock the repository

• If this is a new repository (or you are setting up git-crypt for the first time): Decide where the secure key will be stored outside of the repository (e.g., ~/secure-keys/my-project.key). Proactively run:

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

  Ensure the key is NEVER committed to git.

• If this is a cloned repository containing .enc files: Ask the user for the local path to the existing key file, and run:

  ./skills/secrets-with-git-crypt/scripts/git-crypt-helper.sh unlock /path/to/existing.key
  

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.