Skip to main content

Secrets

Overview​

Secrets are managed using Ansible Vault. The primary source of truth for all encrypted secrets is ansible/secrets.yml. This file is committed to the repository (AES256 encrypted) and is decrypted during provisioning/deployment to generate per-app .env files on the VPS.

diagram

Key Files​

FileDescription
ansible/secrets.ymlAES256 encrypted YAML file containing all secrets.
scripts/vault-set.shCLI tool to sync .env variables into the encrypted vault.
scripts/sync-vault.pyPython script to sync secrets from VPS .env files back into the repo.

Managing Secrets locally​

1. Adding/Updating a secret​

Instead of editing the encrypted YAML manually, use scripts/vault-set.sh. It takes a .env file and upserts its values into the vault:

export ANSIBLE_VAULT_PASSWORD=your_password
./scripts/vault-set.sh path/to/.env

The script will:

  1. Decrypt ansible/secrets.yml to a temporary file.
  2. Compare keys from your .env with the vault.
  3. Update or add keys (prefixed with the app name, e.g., n8n_owner_email).
  4. Re-encrypt and save the vault.

2. Viewing the Vault​

To see the raw content of the vault:

ansible-vault view ansible/secrets.yml --vault-id @prompt

How Secrets are Deployed​

During the Provision VPS workflow:

  1. Ansible decrypts secrets.yml.
  2. The Write all app .env files tasks in playbook.yml map vault variables to specific .env keys.
  3. The .env files are written to /opt/vps-apps/<appname>/.env on the VPS with 0600 permissions.

Syncing Secrets from VPS​

Sometimes secrets are generated or changed directly on the VPS (e.g., Authentik API tokens). To keep the repo in sync, the provision.yml workflow performs a "Sync back" operation:

  1. Dumps all .env files from the VPS.
  2. Decrypts ansible/secrets.yml.
  3. Runs scripts/sync-vault.py to merge VPS values back into the vault content.
  4. Re-encrypts and commits the updated ansible/secrets.yml back to GitHub.

Required GitHub Secrets​

SecretDescription
ANSIBLE_VAULT_PASSWORDThe password used to encrypt/decrypt ansible/secrets.yml.
GH_PATPersonal Access Token used by the workflow to push secret updates back to the repo.
warning

Never commit .env files or plaintext secrets. The .gitignore is configured to exclude all .env files and ansible/secrets.yml must ALWAYS be encrypted before committing.