Skip to content

SOPS and age for encrypted dotenv secrets

The taskfile library supports encrypting project secrets with sops and age.

Setup

Initialize sops and age for the current project:

task init-dotenv-sops

This command:

  • Derives the project name from the git URL.
  • Generates an age key pair.
  • Stores the private key in the sops default location ~/.config/sops/age/keys.txt.
  • Creates .sops.yaml with the age public key.

A custom key name can be given as the first argument:

task init-dotenv-sops taskfile.build

Show the current setup with:

task show-project-setup

List age keys in the default key file:

task list-agekeys

Create encrypted secrets

Create a secrets.env file:

task create-dotenv secrets secrets

Create environment specific secrets such as prod.secrets.env:

task create-dotenv prod.secrets secrets

The secrets template requires .sops.yaml to be present. The created file is encrypted automatically.

Edit and show secrets

Edit an encrypted secrets file with sops:

task edit-dotenv secrets

Show the decrypted content:

task show-dotenv secrets

Load all variables including decrypted secrets into the current shell:

task load-dotenv secrets

Store and load age keys from KeePass

Store the age private key in KeePass:

task store-agekey-to-keepass

Reads the key block matching .sops.yaml from ~/.config/sops/age/keys.txt, stores the secret key in the entry's password field and attaches the key block as keys.txt to the age/<project> KeePass entry. A custom name can be passed as the first argument.

Restore the age private key from KeePass:

task load-agekey-from-keepass

Restores the key block from the age/<project> KeePass entry and merges it into ~/.config/sops/age/keys.txt. A custom name can be passed as the first argument.

CI usage

In CI set SOPS_AGE_KEY to the private key and decrypt secrets.env before using the variables.

Example Forgejo workflow step:

- name: Decrypt secrets
  env:
    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
  run: |
    eval "$(sops --decrypt secrets.env)"
    echo "$KUBECONFIG_DEPLOY" > $HOME/.kube/config

File naming

  • Shared dotenv files live in $TASK_DOTENV_DIR and are named <name>.env.
  • Legacy files named .env.<name> are still supported.
  • Encrypted project secrets live in the project root and are named *.secrets.env.