ansible.cfg

ansible.cfg is where you set the defaults that would otherwise be a wall of command-line flags and environment variables on every run — the inventory path, the SSH user, how many hosts to hit in parallel, whether to verify host keys. Ansible looks for it in four places and the first one found wins outright, with no merging across files, so a config sitting one directory up can silently override the one you think is in effect.

Knowing the search order is the difference between "my setting isn't taking" and a five-minute fix. There is no layering to reason about, no precedence stack to merge in your head — exactly one file is read per run, and the whole skill is knowing which one and how to confirm it. The settings that matter most shape every run, so you put them in the repo once and let the CI runner and every engineer pick up the same behavior.

The Four-Place Search Order

Ansible checks four locations in a fixed order and stops at the first hit. ANSIBLE_CONFIG, an environment variable naming an explicit file, beats ./ansible.cfg in the current working directory, which beats ~/.ansible.cfg in the home directory, which beats /etc/ansible/ansible.cfg. The first file found is the only file read — settings do not layer across them. If the repo's cfg is found, the system-wide one at /etc/ansible is never even opened.

This is the single most useful fact about the file. People reason about it as if a setting in ~/.ansible.cfg would merge with the repo's ansible.cfg and fill in the gaps — it does not. One file wins whole. A setting you expect to inherit from a "lower" file is simply absent if a "higher" file was found first and didn't define it, which is where most "why isn't my setting applying" confusion comes from.

The World-Writable cwd Rule

There is one trap inside that order. Ansible ignores an ./ansible.cfg if the current directory is world-writable, because a config in a directory anyone can write to is an injection vector — someone could drop a malicious cfg and have your run pick it up. The cfg is skipped silently and you fall through to the next location in the search order. This trips people running playbooks from /tmp, which is world-writable by design, where the local cfg you placed is quietly ignored and the run uses unexpected defaults.

Key Connection Settings

A handful of settings shape every run, and they belong in the repo's cfg rather than repeated on the command line. Under [defaults] you set inventory (the host file or directory), remote_user (the SSH user), host_key_checking (whether to verify host keys), and forks — parallelism, defaulting to 5. Under [ssh_connection] you set pipelining, the single biggest performance win, covered three topics on. Set once in the repo, these give everyone identical behavior with no flags to remember.

[defaults]
inventory = inventories/prod
remote_user = deploy
host_key_checking = true
forks = 20

[ssh_connection]
pipelining = true

Every value here would otherwise be an -i, a -u, a -f, or an exported environment variable on every invocation. Pinning them in the file at the repo root means the deploy command is just ansible-playbook site.yml and behaves identically whether a teammate runs it locally or the GitHub Actions runner runs it in CI.

Repo-Local Config as the Norm

The pattern that makes all of this predictable is shipping the cfg in the repo and running from the repo root. The larkspur-io/infra repo carries its own ansible.cfg at the root, pointing inventory = inventories/prod and setting forks = 20. Because the CI runner checks out the repo and runs from that directory, the ./ansible.cfg location wins, and every engineer who clones the repo gets the same inventory and the same parallelism without exporting anything or remembering any flags. The config travels with the code, reviewed in the same pull requests.

Inspecting the Effective Config

When a setting doesn't seem to apply, two commands answer "which file won and what is it setting" without guessing. ansible --version prints the config file actually in use at the top of its output — read that line and you know which of the four locations was selected. ansible-config dump --only-changed then shows every setting that differs from the built-in default, so you see exactly what the live file changes rather than scrolling the full default dump. Run both before you start debugging a behavior you can't explain.