The reference repository layout · Ansible

There is no universal Ansible repository layout, and any document that presents one as settled is hiding a set of trade-offs you will have to make anyway. What follows is a reference layout that works for the common case — one team, one estate, several environments — followed by the alternatives it rules out and why you might rule differently.

Copy the tree. Then read the section on alternatives before you commit to it, because two of the decisions embedded in it are genuinely contested.

The tree

estate/
  ansible.cfg                     # committed; the run's behaviour, not the operator's
  requirements.yml                # collections and external roles, pinned
  requirements.txt                # ansible-core itself, pinned
  README.md                       # written for someone paged at 03:00
  CODEOWNERS                      # who reviews which paths

  inventories/
    production/
      hosts.yml
      group_vars/
        all/
          main.yml
          vault.yml               # encrypted, vault id: prod
        webservers/
          10-tuning.yml
          20-limits.yml
      host_vars/
        web-prod-02.example.com.yml
    staging/
      hosts.yml
      group_vars/
      host_vars/
    development/
      hosts.yml
      group_vars/
      host_vars/

  playbooks/
    site.yml                      # entry point: the whole estate
    webservers.yml                # entry point: one tier
    tasks/
      _preflight.yml              # NOT an entry point; imported only

  roles/
    webserver/
      defaults/main.yml
      tasks/main.yml
      handlers/main.yml
      templates/
      meta/argument_specs.yml
    common/

  collections/                    # installed by requirements.yml; gitignored
  files/                          # large static payloads shared across roles
  scripts/                        # helper tooling; never run by a play
  molecule/                       # role test scenarios

Point an inventory command at one environment directory and the tree resolves without naming a single file — the recursive read picks up hosts.yml and its group_vars/ neighbours together:

Read-only / Safethe layout, read back— Real output from ansible-core 2.21.3. --graph without --vars is safe in a shared terminal even when the tree contains encrypted material.

$ ansible-inventory -i inventories/production --vault-id prod@~/.vault/prod --graph

@all:
|--@ungrouped:
|--@webservers:
|  |--web-prod-01.example.com
|  |--web-prod-02.example.com
|--@databases:
|  |--db-prod-01.example.com

Why each directory exists

The useful question for a layout is not “is this tidy” but “which mistake does this make harder”. Each entry below answers that.

estate/The reference layout, annotated with the failure each directory is there to prevent.

ansible.cfg: committed at the repository root
inventories/<env>/: one directory per environment
inventories/<env>/group_vars/: inside the environment directory
playbooks/: entry points only, plus a tasks/ subdirectory
roles/: shared across every environment
requirements.yml: collections and external roles, version-pinned
collections/: gitignored install target
CODEOWNERS: path to reviewer mapping

01ansible.cfg= committed at the repository root
Fixes the run's behaviour - roles_path, inventory default, forks, callbacks - so every operator and the CI runner behave identically.
Production: Ansible reads the config from the current working directory, so this file is only picked up when the command is run from the repository root. Make that the documented rule and have CI do the same.
⚠ Setting inventory = inventories/ here. Every command that omits -i then loads all environments at once and silently drops every group_vars tree.
02inventories/<env>/= one directory per environment
The environment boundary. A host is in exactly one of these trees, and a run loads exactly one tree.
Production: Distinct filenames matter more than distinct group names. inventories/production/hosts.yml and inventories/staging/hosts.yml cannot be confused on a command line the way -l prod and -l stage can.
⚠ Pointing -i at inventories/ rather than inventories/production/. All environments merge and every group variable is dropped, because group_vars is searched adjacent to the source.
03inventories/<env>/group_vars/= inside the environment directory
Environment-specific policy: which NTP servers, which log target, how many workers.
Production: Keeping it inside the environment directory is what makes the same variable resolve differently per environment without any branching in the role.
⚠ A group_vars/ beside the playbook instead. Ansible reads that one too, and it applies to every environment - so a staging convenience reaches production.
04playbooks/= entry points only, plus a tasks/ subdirectory
Every file directly in playbooks/ is something a human may legitimately run. Everything under playbooks/tasks/ is imported and never run directly.
Production: The convention is what makes ls playbooks/ a truthful answer to "what can I run against this estate". Prefix non-entry-point files with an underscore so the distinction survives a careless reader.
⚠ A partial task file sitting beside site.yml. Someone eventually runs it directly, it has no hosts: line of its own, and the result is either an error or a run against the wrong pattern.
05roles/= shared across every environment
The automation itself. Identical bytes for development and production - that is the entire premise of testing anywhere but production.
Production: A role should be parameterised, never environment-aware. If a role reads the environment name to decide behaviour, the production path is the one your staging run did not execute.
⚠ Copying a role to roles/webserver-prod/ for a production-only tweak. The two copies diverge, and the divergence is discovered during an incident.
06requirements.yml= collections and external roles, version-pinned
Declares the external code the automation depends on, at exact versions.
Production: This file is part of what gets promoted. A change that is "the same commit" but resolved a different collection version is not the same change.
⚠ Omitting version:. The default range identifier is *, meaning most recent - so the same commit installs different code next month.
07collections/= gitignored install target
Where ansible-galaxy places the collections named in requirements.yml, when you choose to install them into the project rather than the user path.
Production: Gitignore it and install in CI. Committing the installed tree makes diffs unreadable and hides the version pin behind thousands of vendored files.
⚠ Committing it "so CI is faster", then editing a file inside it to fix a bug. The fix is invisible to every reviewer and disappears at the next reinstall.
08CODEOWNERS= path to reviewer mapping
Requires a named reviewer for the paths whose breakage causes an outage.
Production: Scope it to the dangerous paths - inventories/production/, roles/ that manage storage or the network - rather than the whole repository. A CODEOWNERS matching everything is a queue, not a control.
⚠ Owning only the roles and leaving inventories/production/ unowned. Most wrong-target incidents are inventory changes, not role changes.

Contested decision 1: directories or branches per environment

Some teams put each environment on its own long-lived Git branch — main is production, staging is staging — instead of in separate directories on one branch. It is a real pattern with real adherents, and it is worth understanding rather than dismissing.

	Directories on one branch	A branch per environment
How a change reaches production	Merge once; the change is present for all environments immediately	Merge to `staging`, then merge `staging` into `main`
What a reviewer sees	Every environment’s version of the change, in one diff	One environment’s version; the others are a later merge
Risk profile	A production-affecting mistake is visible at review time — and is also merged at review time	Production is protected by a second merge — and the branches drift
Drift	Structurally impossible; there is one copy	The normal outcome. A hotfix on `main` that is never back-merged is invisible until the next promotion conflicts
“What is production running?”	A commit plus an inventory path	A commit on a specific branch, which may not contain fixes that exist on another
Rollback	Revert the commit	Revert on the branch, then reconcile the others

The honest summary: branches trade an immediate risk for a slower, quieter one. The immediate risk is that on a directory layout a merged change is live for production the moment production next runs. The quieter risk is that branches diverge, and divergence is discovered at the worst time — during a promotion, under pressure, when the merge conflict is in a file nobody remembers.

The directory layout handles the immediate risk with the thing that is actually load-bearing: production runs from a tag, not from whatever main happens to contain. That decouples “merged” from “deployed” without creating a second copy of the automation. Lesson 5 and Part XXXVIII’s branching lesson cover the mechanics.

Choose branches only if you have a concrete reason the directory form cannot serve — for example, two environments genuinely running different major versions of the automation for a long migration. Then treat the divergence as a project with an end date, not a permanent structure.

Contested decision 2: one repository or several

The reference layout is one repository. The alternatives are worth naming because the pressure to split arrives around the time the repository gets useful.

Split roles into their own repositories when a role is consumed by more than one estate, or by a team that does not own this repository. Then it is a dependency with a version, pulled in through requirements.yml, and it gets its own tests and its own release cadence. That is a genuine benefit and a genuine cost: every change now requires a release and a bump, which is exactly the friction you want for shared code and exactly the friction you do not want for code only you use.

Split inventory from automation when the people who add and remove hosts are not the people who write plays — a common shape once an estate has a provisioning team. The inventory repository then has its own review rules and its own change rate, which is usually much higher.

Do not split per environment. Two repositories, one for staging and one for production, is the branch-drift problem with worse tooling: there is no merge to conflict, so the divergence is completely silent.

Under the hood

Whichever way you split, the mechanism underneath is roles_path and the collection search path, and it is worth knowing where a role actually comes from before you rearrange the repository around it.

ansible.cfg sets roles_path; a role named in a play is looked for in roles/ beside the playbook first, then along that path, then inside installed collections as namespace.collection.rolename. The practical consequence is that a role vendored into roles/ shadows a role of the same name pulled from a collection, silently and with no warning.

That shadowing is occasionally useful — it is how you patch a third-party role in an emergency — and it is a maintenance trap the rest of the time, because the vendored copy stops receiving upstream fixes and nothing tells you. If you do it, do it deliberately: keep the vendored copy under a different name, or leave a comment at the top of tasks/main.yml saying what it forks, from what version, and what has to happen before it can be deleted.

ansible-config dump --only-changed shows the effective roles_path for the current working directory, which is the fastest way to answer “where did that role come from” when two answers are plausible.

Contested decision 3: vendored roles or requirements.yml

For a role you did not write, there are two options and one of them is usually wrong.

Pinned in requirements.yml is the default answer:

---
collections:
  - name: community.general
    version: "==11.4.0"
  - name: ansible.posix
    version: ">=3.0.0,<4.0.0"

roles:
  - name: geerlingguy.java
    version: "1.9.6"

The version key takes the range identifiers *, !=, ==, >=, >, <= and <, and they can be combined with a comma. Ranges work for collections; for roles, only an exact version is supported. Omitting version entirely means * — most recent — which is how a repository that has not changed in six weeks starts behaving differently.

Vendored into roles/ is right in narrow cases: the upstream is unmaintained, or your estate needs a fork you cannot upstream, or you are in an air-gapped environment where the install step cannot reach a galaxy server. In every one of those, record why in the role, because the reason is what tells a future maintainer whether the fork can be retired.

What you should not do is vendor a role because pinning felt like extra work, and you should not commit the collections/ install target for the same reason. Both hide the version behind a wall of files that no reviewer will read.

What happens if two environments need different collection versions?

Occasionally legitimate: production runs RHEL 8 for another quarter and needs a collection release that still supports it, while everything else has moved on.

The wrong answer is a second requirements.yml per environment, because that breaks the promotion model — the thing you tested in staging is no longer the thing production runs, and you have reintroduced branch drift by another name.

The workable answers, in order of preference:

Find a version that satisfies both. Usually one exists, and the cost is a slightly older collection everywhere for a quarter.
Treat the laggard as a separate estate, with its own repository, its own pin and its own end date. This is honest about what is happening: you are running two automations, and you should be able to say so.
Pin in requirements.yml and select at install time in CI, with a loud comment and a ticket. This is the pragmatic option and it should feel temporary, because it is the state in which a promotion no longer proves what it claims.

Whichever you choose, write the end date down. A version split with no end date becomes permanent within two quarters, and the estate then has two production paths and one test path.

The tree

Why each directory exists

Contested decision 1: directories or branches per environment

Contested decision 2: one repository or several

Contested decision 3: vendored roles or requirements.yml

Knowledge check