Ansible collection and role pinning — requirements.yml with version constraints

Ansible collections and roles are pulled from Galaxy, Git, or a private automation hub at runtime. The requirements.yml file declares the consumer intent — which collections and roles the playbook needs, in what version range. The resolution is performed by ansible-galaxy against the registry; the registry can publish a new satisfying version between two consecutive runs, and the run will pick up the new version without any change to the playbook. The discipline of pinning binds every collection and every role to a content address and reviews the upgrade.

Pin collections by exact version in requirements.yml

A collection pin takes the form namespace.collection:version. An exact pin freezes the version; a range narrows the selection but leaves drift open.

# collections/requirements.yml
collections:
  - name: community.general
    version: "8.3.0"
  - name: amazon.aws
    version: "7.2.0"
  - name: kubernetes.core
    version: "3.0.0"

The version: "8.3.0" is an exact pin. The ansible-galaxy collection install -r collections/requirements.yml command resolves each collection to the pinned version and downloads the artifact from Galaxy. A playbook that pins version: ">= 8.0" instead is a playbook whose bytes are chosen by Galaxy at install time.

flowchart LR
    A["Range constraint"] --> B["Galaxy resolves"]
    B["Galaxy resolves"] -. "new version" .-> C["Different bytes today"]
    D["Exact version"] --> E["Artifact v8.3.0"]
    E["Artifact v8.3.0"] --> F["Same bytes forever"]

The Galaxy artifact is a tarball served from galaxy.ansible.com or from a private automation hub. The tarball has a SHA-256 checksum published alongside it; the checksum is the content address. The exact version pin freezes the tarball; the checksum verification confirms the bytes.

Pin roles by source, scm, version, and name

Roles can be pulled from Galaxy (the same registry as collections) or directly from a Git repository. A role pin that uses scm: git must also pin version: to a branch, a tag, or a commit SHA.

# roles/requirements.yml
roles:
  - name: geerlingguy.docker
    version: "3.1.1"
  - name: my-org.internal-role
    src: https://github.com/my-org/ansible-role-internal.git
    scm: git
    version: 7d4f2a1c9b8e6f3a2c1d4e5f6a8b9c0d1e2f3a4b

The Galaxy role pin (geerlingguy.docker) freezes the artifact version. The Git role pin (my-org.internal-role) freezes the commit SHA; the SHA is the content address and cannot be moved without rewriting history. A Git role pin that uses version: main is a role pin whose bytes are chosen by the upstream at install time.

Resolution and verification

The ansible-galaxy resolution is the moment the registry is consulted. The production discipline is to resolve in a controlled step (CI, an isolated runner, a deliberate operator action), record the resolved artifact, and ship the artifact to the runtime without re-resolution.

# CI: resolve against Galaxy, install into the local collection path
ansible-galaxy collection install -r collections/requirements.yml -p ./collections
# CI: resolve Git roles, install into the local role path
ansible-galaxy role install -r roles/requirements.yml -p ./roles

The CI step records the resolved versions and the checksums. The runtime uses the local collections/ and roles/ paths; the runtime does not contact Galaxy. The registry is consulted once, under review, and the result is vendored into the build.

# Runtime: use the local vendored collections and roles
ansible-playbook site.yml \
  --collections-path ./collections \
  --roles-path ./roles

Re-pinning as a deliberate upgrade

A collection or role upgrade is a supply-chain change. The workflow is:

1. Identify the upgrade. Read the upstream release notes and advisories.
2. Resolve the new version. Update requirements.yml with the new exact version or the new commit SHA.
3. Run ansible-galaxy install to verify the new artifact downloads and matches the checksum. Fail the PR if the checksum does not match.
4. Run the playbook’s test suite (molecule or equivalent) against the new artifact. The suite is the team’s evidence that the upgrade does not break the playbook.
5. Commit the updated requirements.yml in a pull request. The PR contains the new version, the resolved checksum, the upstream release notes, and the test results.

A Renovate-equivalent bot can automate step 2 and open the PR in step 5; the team still performs steps 3 and 4.

Production discipline

1. Pin every collection by exact version. No >= or ~> for security-critical playbooks.
2. Pin every Git role by commit SHA. No main or master refs.
3. Verify the checksum at install time. A download without a checksum verification is a supply-chain hole.
4. Vendor security-critical collections and roles. The registry is consulted once, under review; the runtime executes the vendored copy.
5. Re-pin deliberately. A collection or role bump is a supply-chain change.

Cross-course references

• Git, CI/CD & GitOps — Part LXVII-01 (Pinning Discipline) defines the discipline that motivates collection pinning.
• Git, CI/CD & GitOps — Part LI-05 (Molecule) covers the integration tests that validate a collection or role upgrade.
• Ansible for Production Sysadmins — Part XXXVII (RepoArch) covers the repository layout that hosts vendored collections and roles.
• Linux for Production Sysadmins — Part XXXIV (ConfigMgmt) covers the configuration-management analogue at the OS level.

Quiz