Galaxy, requirements.yml & pinning

Lesson 4 left you with one command: ansible-galaxy collection install community.general. It works, and it’s also a trap: it installs whatever version is latest today, onto your machine only. Fine for a laptop experiment; useless as a team workflow. This lesson covers where that command reaches, how a project declares its needs in one committed file, and why the version pin saves you.

The command talks to Galaxy — Ansible’s public hub at galaxy.ansible.com for collections and community roles — via the ansible-galaxy CLI. Two install verbs cover both kinds of content:

ansible-galaxy collection install community.general   # a collection, from lesson 4
ansible-galaxy role install geerlingguy.nginx         # a standalone role from the hub

The second verb matters because Galaxy predates collections: thousands of standalone roles (lesson 24’s unit of reuse) live there under author.rolename names, and plenty of teams still consume them directly.

The manifest: requirements.yml

A real repo doesn’t document dependencies in a README. It commits a manifest named requirements.yml:

# requirements.yml
collections:
  - name: ansible.windows
    version: 3.5.0             # exact pin — every install identical
  - name: community.general    # unpinned — grabs latest today (avoid)
roles:
  - name: geerlingguy.nginx    # roles list the same way, version: included

The shape is what you see: a collections: list and a roles: list, each entry a dict with name: and — always, in a repo you respect — version:. One command installs everything the file names:

ansible-galaxy install -r requirements.yml   # installs both lists

That command is how a fresh clone becomes runnable. You’ll meet it again verbatim in lesson 41: the Jenkins pipeline pattern starts this way — check out the repo, ansible-galaxy install -r requirements.yml, run the playbook. The CI agent starts empty every time; the manifest makes that a feature instead of a failure.

In the standard repo layout (lesson 36) you’ll usually find the manifest split in two — collections/requirements.yml and roles/requirements.yml — same shape, one kind of content per file.

Pin it

An unpinned entry means “latest at the moment of install.” You installed in March, the CI agent installs tonight, the new teammate installs in August: three collection versions, one Git commit, and a bug that reproduces on only one machine. You already own the instinct that prevents this — it’s a lockfile. The same reflex that pins a Docker base image to a real tag instead of :latest applies here: exact version: pins, upgraded deliberately in a reviewed commit, never as a side effect of install day.

Pinning also connects this file to the execution-environment world of lesson 40. There, dependencies get baked into a container image at build time instead of installed on the control node — but they’re built from this same manifest. Either way the habit is identical: the moment a playbook uses a collection outside the bundle from lesson 5, it goes into requirements.yml with a version — not just into your machine’s collection path. The next person to clone the repo is counting on it, and so is the CI runner that deploys it.