ansible-vault encrypt: Usage & Common CI Errors

Encrypt secrets at rest so they can live safely in your repo.

ansible-vault encrypt protects variable files and secrets with a password so they can be committed. In CI you supply the password from a file or env so playbooks can decrypt at runtime without a prompt.

What it does

ansible-vault encrypt <file> rewrites a plaintext file as an AES256-encrypted vault blob. Playbooks read it transparently when given the vault password. Companion commands are encrypt_string (inline encrypted values), decrypt, edit, rekey, and view.

Common usage

# Encrypt a vars file in place
ansible-vault encrypt group_vars/prod/secrets.yml

# Encrypt a single string for inline use in YAML
ansible-vault encrypt_string 's3cr3t' --name 'db_password'

# CI: decrypt / run using a password file (no prompt)
ansible-playbook site.yml --vault-password-file .vault_pass
ansible-vault view secrets.yml --vault-password-file .vault_pass

Common error in CI: decryption failed / prompt blocks the job

CI fails with "ERROR! Attempting to decrypt but no vault secrets found" (no password supplied) or "Decryption failed" (wrong password), and an interactive ansible-vault call simply hangs waiting for input. Fix: always pass --vault-password-file (a file the runner writes from a CI secret) or set ANSIBLE_VAULT_PASSWORD_FILE; never rely on the interactive prompt in CI. For multiple vaults, use --vault-id labels so the right key decrypts the right file.

Key options

Related guides