Pin each entry in requirements.yml to an exact version. Collections accept a version or a range, defaulting to any version, while the documentation notes that ranges are not supported for roles. A pinned file turns your dependency list into something you can review.
What the file looks like
collections:
- name: my_namespace.my_collection
version: "1.2.0"
- name: my_namespace.other_collection
version: ">=1.2.0"
roles:
- name: example.java
version: "1.9.6"
The same format can list a role and a collection together. The version field for collections takes a version range identifier and defaults to *, meaning any. You can also give a source to pull a collection from a particular server.
Why pinning matters
Without a pin, the next install gets whatever is current. A change in a collection you depend on can enter a run with no change in your own repository. A range like >=1.2.0 has the same problem in a milder form.
Pin choices
| Entry | Effect | Review burden |
|---|---|---|
| No version | Latest at install time | Hard to reason about |
| Range | Anything in the range | Medium |
| Exact version | One version | Lowest, but you must update by pull request |
| Exact version plus signatures | One version and key checked | Lowest |
Add signatures for extra assurance
Entries can include a signatures list. That ties into the keyring workflow: Ansible checks the listed detached signatures, in addition to those the server provides. See the separate post on signed collections for the limits, which include Git and tar based installs.
Review checklist
- Every entry has an exact version.
- Every entry has a source you recognize, and a
sourcekey when you use a private server. - Entries from Git or URLs are flagged, since signature verification does not cover them.
- Dependencies of dependencies are checked, since the verify command does not include them.
- Updates arrive as pull requests with release notes linked.
Keep a record
Treat the file as your inventory of automation dependencies. Store it in version control, and note which playbooks use which collections. When an advisory appears, you can answer which control nodes and pipelines are affected.
Quick check
Can I use a version range for roles?
The documentation says ranges are not supported for roles. Pin an exact version.
What is the default version for a collection?
Any version, written as an asterisk.
Where do I list roles?
Under the roles key in the same requirements file.
Safeguard offers SBOM and dependency scanning and policy gates that can block a pull request on findings, and you can try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
