What belongs in the repository, and what must not · Ansible

The repository is the recovery plan. Not the backup, not the runbook — the repository, because it is the only artefact that already exists on more than one machine as a matter of routine and is already replicated by a system somebody else operates.

That makes the contents of the repository a DR decision rather than a tidiness decision. Everything in it survives the controller. Everything outside it has to be explicitly arranged for, or it does not.

There is a second requirement pulling the other way, and the two have to be satisfied at the same time:

What must be in the repository

Playbooks, including the site composition that imports them - a playbook that only ever existed as a file on the controller is a playbook you will rewrite from memory.
Roles, including their defaults, handlers, templates and files. If a role is consumed from Galaxy or an internal server, its pinned entry in requirements.yml stands in for it.
Static inventory files, group_vars and host_vars - excluding the plaintext secrets, which are covered below.
Dynamic-inventory plugin configuration: the .aws_ec2.yml or .proxmox.yml file that tells the plugin what to query. The credentials it uses do not go here.
The project ansible.cfg. This is the settings file the fleet behaviour depends on, and Part VI showed how much it changes.
requirements.yml, with versions pinned. Without this the collection set is unrecoverable knowledge.
Vault-ENCRYPTED variable files and encrypt_string values. These are safe to commit; that is the entire point of encrypting them.
The controller build definition: the pinned dependency list from lesson 3, or the execution-environment.yml from lesson 5.
The rebuild runbook itself, so that the instructions for restoring the controller are not stored on the controller.

The last item is the one teams forget, and it has the flavour of a joke until it happens. A rebuild runbook stored on a wiki that authenticates against an LDAP server managed by the automation you cannot run is the same failure in a different suit.

What must never be in the repository

Never commit	Where it lives instead
The vault password, in any form	Escrow (lesson 4), a secret manager, or an operator’s password manager
A `vault_password_file` containing the password	Same. Committing the path in `ansible.cfg` is fine; committing the file is not
SSH private keys for the automation account	Escrow, or generated fresh per controller with the public key deployed by an existing play
API tokens for dynamic inventory or cloud modules	The environment, a secret manager, or an encrypted vault file
Become/sudo passwords in plaintext	A vault file, or eliminated with `NOPASSWD` for specific commands
`~/.ssh/known_hosts`	Regenerated; see the note below on why committing it is tempting and wrong
Anything the CI system decrypts and prints	Nothing changes about the file; the leak is the pipeline, and Part XLVIII covers it

A committed secret is not removed by deleting it

This is the property that makes rule 2 absolute rather than a preference.

Committing a credential and then removing it in the next commit leaves it in the history, in every clone anyone ever made, in every fork, in the reflog of every developer who fetched it, in the CI cache, in any mirror, and in the search index of whichever code-search tool your organisation runs.

git rm deletes the file from the working tree. A history rewrite deletes it from your copy of the history and from nobody else’s until they all re-clone, which they will not. Assume that from the moment of the push, the secret is public, and remediate accordingly — which means rotating the credential across the fleet, under exactly the partial failure conditions Part XLIV describes.

Part LII lesson 2 catalogues this as an anti-pattern and works through the remediation. Here the point is narrower: this is why the two-failure test has an absolute side.

The three categories of accidental controller state

The visible failures are easy. What breaks rebuilds is state that accumulated on the controller without anyone deciding to put it there.

1. Files Git was never told about

Read-only / Safeuntracked and ignored files in the project tree— Read-only. --untracked-files=all descends into untracked directories rather than reporting the directory alone; --ignored reveals files a .gitignore rule is hiding, which is where a hand-written vars file often sits.

cd /srv/ansible

# Everything git does not track, file by file.
git status --short --untracked-files=all

# Files an ignore rule is deliberately hiding. Read every line.
git status --short --ignored

# Local commits that were never pushed anywhere.
git log --branches --not --remotes --oneline

The --ignored listing is the interesting one. A .gitignore entry for *.local.yml or secrets/ is usually correct and usually also the place where a genuinely needed file has been quietly excluded. Read the list and decide, per file, whether it is regenerable, escrowed, or neither.

2. Configuration that is not the project’s

ansible.cfg has a search order, and only one position in it is inside the repository.

Read-only / Safewhich configuration file is actually in effect— Real output from ansible-core 2.21.3 in a directory with no project config. `config file = None` means the run is using built-in defaults - and on the destroyed controller it may instead have said /home/ansible/.ansible.cfg, which is not in any repository.

$ ansible --version

ansible [core 2.21.3]
config file = None
configured module search path = ['/home/ansible/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible collection location = /home/ansible/.ansible/collections:/usr/share/ansible/collections
python version = 3.14.4

The search order — ANSIBLE_CONFIG, then ./ansible.cfg, then ~/.ansible.cfg, then /etc/ansible/ansible.cfg — was covered in Part VI. The DR consequence is one sentence: if the effective config file is not the one in the repository, the rebuilt controller behaves differently from the destroyed one, and nothing will tell you.

The settings that bite are the quiet ones. A ~/.ansible.cfg carrying host_key_checking = False or a raised forks or a roles_path pointing at a directory outside the project does not fail on the new controller; it just behaves differently, and the difference shows up as a run that is slower, or that fails a host-key prompt, or that cannot find a role.

Read-only / Safecapture the effective settings before you need them— Read-only. --only-changed prints just the settings that differ from the built-in defaults, which is the short list worth reading. Run it on the live controller and keep the output with the runbook.

ansible-config dump --only-changed

# The same, but showing which source set each value.
ansible-config dump --only-changed -v

Anything in that output that is not explained by the committed ansible.cfg is undocumented controller state.

3. Software installed by hand

Read-only / Safecollections actually present on the controller— Real output from ansible-core 2.21.3 on a controller with no collections installed. On a real one this prints a path header followed by every collection and version - and every line not accounted for by requirements.yml is a rebuild failure waiting to happen.

$ ansible-galaxy collection list

Compare that listing against requirements.yml by hand once. The difference is the set of collections somebody installed during an incident and never recorded. Lesson 3 makes this comparison systematic; here it is one of the three audits.

Under the hood

Why is known_hosts on the “do not commit” list when it is not a secret?

It is not about confidentiality. It is about what a committed known_hosts means operationally.

Host key checking exists to detect a man-in-the-middle: the first connection records the host’s key, and every later connection verifies it. A known_hosts file committed to the repository turns that into a distributed trust store — which sounds like an improvement, and is occasionally implemented deliberately as one — but it has two failure modes that make it wrong as a default.

First, it goes stale in a way that fails closed and loudly. Rebuild a managed node and its key changes; now every controller with the committed file refuses to connect until somebody edits the repository. The pressure at that moment is to disable host key checking entirely, which is the outcome Part XLVII warns about.

Second, the file records which hosts you connect to, along with their key types. On a public or widely-readable repository that is reconnaissance, and HashKnownHosts exists precisely because that information is considered worth protecting.

The rebuild answer is to regenerate it deliberately: ssh-keyscan against the inventory as an explicit, reviewed step, or the ansible.builtin.known_hosts module driven from an inventory the repository already contains. Both make the trust decision visible at rebuild time, which is when you want to be making it.

The audit, as a single pass

git status --short --untracked-files=all - decide, per file: commit it, escrow it, or accept losing it.
git status --short --ignored - read every ignored path and confirm nothing needed is hidden there.
git log --branches --not --remotes --oneline - push it, or accept losing it.
ansible --version | grep "config file" - confirm it names the repository copy.
ansible-config dump --only-changed - confirm every changed setting is explained by the committed ansible.cfg.
ansible-galaxy collection list - confirm every collection appears in requirements.yml with a version.
grep the repository for anything that looks like a credential, then look again at group_vars and host_vars specifically.
Read the rebuild runbook and confirm no step depends on a system that depends on the controller.

Eight commands, all read-only, and it takes about twenty minutes. It is worth scheduling quarterly, because every item on it drifts.

What happens if the repository contains vault-encrypted files but you are not sure the password still decrypts them?

Find out now, because the answer is cheap today and catastrophic during a rebuild.

The check is a decryption that changes nothing:

ansible-vault view group_vars/production/vault.yml

If it prints the plaintext, that password decrypts that file. If it reports a decryption failure, one of three things is true, and they need different responses.

Wrong password entirely. The file was encrypted with a different secret — commonly because the repository has more than one vault ID and you supplied the wrong one. ansible-vault view --vault-id prod@prompt against each ID you know about will find it.

Right password, rotated file. Somebody re-encrypted the file with a new password and updated their own copy without updating the escrow. This is the failure the break/fix scenario for this part is built on, and it is invisible until you try.

Right password, and it decrypts — but only for that file. A repository can carry several vault IDs with different passwords, and proving one works proves nothing about the others. The check has to iterate over every encrypted file, not a sample.

That last point is why lesson 4 insists on periodic proof rather than periodic confidence. Enumerate the encrypted files, decrypt each one, and record the date. A grep for $ANSIBLE_VAULT across the repository gives you the list.

Knowledge check

Why this matters

Most repository-hygiene advice is presented as tidiness, which is why it loses arguments against delivery pressure. This lesson reframes it as two failures with names.

If the repository is missing something, the controller cannot be rebuilt, and the estate becomes unmanageable at the moment you most need to manage it. If the repository contains a secret, a stolen clone is a fleet compromise, and the remediation is rotating every credential across four hundred hosts using automation whose credentials you are mid-rotation on.

Those are the only two questions, and every artefact answers both. The lists in this lesson are not opinions about project layout; they are the output of applying the test.

The audit is eight read-only commands. Run it once and you will find something — every team does, and it is usually the home-directory ansible.cfg or a collection installed during an incident nine months ago. Finding it on a quiet Tuesday costs twenty minutes. Finding it during a rebuild costs the rebuild.