Every Ansible collection you install becomes code that runs with the privileges of your automation, on every host it touches, so the path from a Galaxy namespace to your controller is part of your attack surface. A playbook that reaches thousands of servers through one execution environment will run whatever version of community.general or a partner collection was resolved at build or sync time. This guide covers how to control that path: requirements files and version pinning, server lists and tokens, GPG signature verification with ansible-galaxy, private automation hub repositories and approval, project signing with ansible-sign, and execution environment builds. It is for platform engineers, automation teams and the security architects who review them. For controller credentials, RBAC and Vault, see the Ansible and AWX Security Guide; this page does not repeat that material.
This is an independent guide from NHI Mgmt Group, based on the Ansible project's public documentation and Red Hat's public Ansible Automation Platform documentation as of November 2026. It is not sponsored or reviewed by the Ansible project or Red Hat. Product features change, so confirm settings against the current documentation.
Key takeaways
- A range is not a pin.
ansible-galaxyalways installs the most recent version that meets your range, and the default range is*, so an unpinned requirements file changes what runs every time it is resolved. - Signatures cover distribution servers only. GPG verification applies to collections installed from a Galaxy or automation hub server; git, directory, tarball and URL installs need a different integrity control, such as pinning to a commit and signing the project.
- Make verification strict on purpose. The default
required_valid_signature_countis 1; prefix it with+so an install fails when no valid signature is found, and keepdisable_gpg_verifyat its default of False. - Put a curated hub between Galaxy and production. Private automation hub syncs only the collections and versions you list, routes uploads through staging and approval, and can sign approved content with your own key.
- Hub and Galaxy tokens are non-human identities. Private automation hub API tokens do not expire and the console.redhat.com offline token expires after 30 days of inactivity, so both need an owner, a vault location and a rotation routine.
How collection content reaches your automation
Collections arrive through several routes, each with its own integrity control.
| Route | How it is declared | Integrity control available | Main risk if left open |
|---|---|---|---|
| Public Galaxy (galaxy.ansible.com) | ansible-galaxy collection install ns.name or requirements.yml with type: galaxy | Version pinning; GPG signatures where the server provides them | New versions and transitive dependencies resolved without review |
| Private automation hub | [galaxy_server.<id>] entry or controller Galaxy credential | Curated sync, approval pipeline, hub-applied signatures | Community remote syncing every version because no version was set |
| Git repository | git+https://...,<commit or tag> or type: git | Pin to a commit; sign the consuming project with ansible-sign | Branch references that move; credentials embedded in the URI |
| Tarball or URL | type: file or type: url | Checksum and storage controls you build yourself | Artefacts copied between systems with no provenance record |
| Execution environment image | dependencies.galaxy in the ansible-builder definition | Pinned requirements at build time; container image signing on the hub | Images rebuilt from floating ranges, so two builds of the same tag differ |
| Controller project sync | collections/requirements.yml in the SCM repository | Content Signature Validation Credential; hub-only Galaxy credentials | Project collections take precedence over the image's copies, even older ones |
Red Hat's documentation states that collections specified in a project's requirements.yml take precedence when a job runs, which means a carefully built and signed execution environment can be overridden by whatever a project sync pulls. Decide which layer owns collection versions, and make the other layer agree with it.
Red Hat also distinguishes three classes of content. Ansible Certified Content Collections are part of the Automation Platform subscription and carry joint Red Hat and partner support; Ansible validated content offers an expert-led path for operational tasks; and community collections on Galaxy are the latest community content with no joint support claims. Use these as trust tiers: review rises as the support claim falls.
Requirements files and version pinning
The requirements file is the bill of materials for your automation. A collections: list takes name, version, signatures, source and type per entry. Version ranges accept *, !=, ==, >=, >, <= and <, combined with commas. Pre-releases are ignored unless you request one explicitly with ==. Roles listed in the same file do not support ranges at all.
| Specifier | Example | What gets installed | Use it for |
|---|---|---|---|
None or * | community.general | Highest available version at resolve time | Local experiments only |
| Bounded range | '>=9.0.0,<10.0.0' | Highest version inside the range | Development branches that track a major version |
| Exact pin | ==9.4.0 | That version only | Production execution environments and controller projects |
| Exclusion | '>=9.0.0,!=9.2.1' | Highest version except the excluded one | Blocking a known bad release while a fix lands |
| Git commit | git+https://host/repo.git,<sha> | The exact commit | Internal collections not yet published to a hub |
- Pin transitive dependencies too: A collection's
galaxy.ymldeclares its owndependencieswith range specifiers, and"*"there selects the highest version available. List each dependency you rely on explicitly with an exact version so a dependency release cannot change your build. - Set
sourceon every entry: Without it the entry defaults to the--api-serveror server list. Naming the hub URL per entry makes the intended origin reviewable in a pull request. - Keep credentials out of git URIs: The Ansible documentation warns that embedding credentials in a git URI is insecure. Use SSH keys or a credential helper owned by the build identity.
- Raise the version mismatch setting:
COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCHdefaults towarning; set it toerrorin pipelines so a collection that declares no support for the running ansible-core stops the play instead of running anyway. - Review lock changes like code: Treat any change to a requirements file as a dependency upgrade that needs a reviewer, a test run and a changelog read. See the Malicious Package and Dependency Confusion Guide for the wider discipline.
Galaxy server lists, tokens and trust order
The [galaxy] section of ansible.cfg controls where ansible-galaxy looks. server_list names an ordered set of [galaxy_server.<id>] sections, and servers are searched in that order until the collection is found. Single-server commands such as publish, info and install use the first entry unless --server is passed, and passing a URL to --server ignores the list entirely. Without a server list, GALAXY_SERVER defaults to https://galaxy.ansible.com.
- Put the private hub first, or alone: Search order is a trust decision. If public Galaxy sits in the list after your hub, any name your hub does not carry falls through to the public server. For production, list only the hub repositories you approve.
- Per-server keys: Each server section takes
url(ending in/),tokenorusernameandpassword,auth_url,client_id,validate_certsandtimeout. Environment variables followANSIBLE_GALAXY_SERVER_{ID}_{KEY}, which suits injecting tokens from a secrets store at run time. - Never pass tokens on the command line: The distribution guide states that
--tokenis insecure because other users on the system may see it, and recommends a server list entry instead. One token per distribution server. - Keep TLS validation on:
ignore_certsand the per-servervalidate_certsexist for self-signed lab servers. In controller, Red Hat's documentation describes the Ignore Ansible Galaxy SSL Certificate Verification job setting as something to enable only for hubs with self-signed certificates. - Know where tokens sit on disk:
GALAXY_TOKEN_PATHdefaults togalaxy_tokenunderANSIBLE_HOME, typically~/.ansible/galaxy_token. Include it in secret scanning on laptops and build agents.
Signature verification with ansible-galaxy
Distribution servers that support signing publish ASCII-armoured, detached GPG signatures over each collection's MANIFEST.json, and ansible-galaxy checks those signatures before it checks the collection's contents. The relevant controls are:
| CLI option | ansible.cfg key ([galaxy]) | Default | Recommended production value |
|---|---|---|---|
--keyring | gpg_keyring | Not set | A dedicated keyring, for example ~/.ansible/pubring.kbx, holding only your hub's collection key |
--required-valid-signature-count | required_valid_signature_count | 1 | +1, or +all where every supplied signature must validate |
--ignore-signature-status-code | ignore_signature_status_codes | Not set | Empty; add a code such as NO_PUBKEY only with a documented reason |
--disable-gpg-verify | disable_gpg_verify | False | False, and alert on any change |
--signature | Requirements key signatures | Not set | Extra detached signatures over HTTPS or file://, for example a second approver's key |
The + prefix is the important detail: it makes verification fail when no valid signature is found, rather than passing a collection that simply has none. Even with ignored status codes, verification still fails if too few signatures are valid.
Red Hat's procedure imports the hub's public key into a non-default keyring with gpg --import --no-default-keyring --keyring ~/.ansible/pubring.kbx, then passes --keyring to both install and verify. Keys are downloaded from Automation Content > Signature Keys, where collection keys are prefixed collections- and container keys container-.
Verifying what is already installed
ansible-galaxy collection verify ns.name compares an installed collection with the copy on the configured server and lists any changed files; it prints nothing on success, and -vvv shows the version, path and remote URL used. Name a version with ns.name:version, otherwise the installed copy is compared with the latest version on the server. Points to plan for:
- Verify dependencies explicitly: With
-r requirements.yml, only the listed collections are checked, so list every dependency in the file you verify against. - Handle archives separately: Verifying against
tar.gzfiles is out of scope for the command;--ignore-errorslets it skip those entries and process thenamespace.nameones. - Use saved signatures in air-gapped runs: Signatures collected at install time are stored with the collection, and
--offlineverifies against them without querying the server.
Private automation hub as the trust boundary
Private automation hub is the Red Hat component that hosts collections and execution environment images inside your network. Its repositories form a pipeline, and configuring it deliberately is the single biggest supply chain control available in the platform.
| Repository | Purpose | Configuration to set |
|---|---|---|
rh-certified remote | Syncs Ansible Certified Content Collections from console.redhat.com | Sync URL and token from console.redhat.com; a requirements file to limit what is synced |
community remote | Syncs chosen collections from Ansible Galaxy | YAML requirements with an exact version per entry |
validated | Holds Ansible validated content | Loaded by the RPM bundle installer by default; review what you expose |
Staging (pipeline=staging) | Receives uploads from anyone with namespace upload rights | Restrict namespace upload rights to named teams |
Approved (pipeline=approved), e.g. Published | Content users can view and download | Accepts content only after approval from staging |
- Specify versions on the community remote: Red Hat's documentation warns that leaving out the version syncs all versions of a collection. That publishes unreviewed versions.
- Require approval: Set
automationhub_require_content_approvalin the installer inventory and leave auto approve off for production, so an administrator chooses the target approved repository for each upload. - Sign on approval: The installer variables
automationhub_create_default_collection_signing_service,automationhub_collection_signing_service_keyandautomationhub_collection_signing_service_scriptconfigure a signing service, andautomationhub_auto_sign_collectionssigns on approval. The signing script receives a file name, signs it with the key inPULP_SIGNING_KEY_FINGERPRINTand returns JSON withfileandsignaturekeys. Approvers can also sign or re-sign from Collection Approvals. - Create namespaces before upload: Private automation hub requires a namespace to exist before content is uploaded to it, which gives you a natural ownership checkpoint. Namespaces use lowercase letters, digits and underscores only.
- Allowlist only what sync needs: Red Hat lists the domains the hub must reach, including galaxy.ansible.com, console.redhat.com and sso.redhat.com. Restrict egress to those.
Published versions are immutable on a distribution server: re-uploading an existing version returns conflict.collection_exists. That protects consumers from a silent swap of a pinned version, and it means a fix always ships as a new version number that your pins must adopt deliberately. For the general pattern of curated internal mirrors, see the Private Package Repository and Proxy Guide.
Controller projects and execution environments
Project sync
Automation controller installs collections from collections/requirements.yml and roles from roles/requirements.yml during the project sync that runs before a job. Three settings decide what that sync can reach:
- Galaxy credentials on the organisation. Create an Ansible Galaxy/Automation Hub API Token credential for each hub repository, as Red Hat's documentation requires a separate credential per repository, then attach only the approved repositories' credentials to each organisation. Different organisations can be given different repositories.
- System-wide download switches. Enable Collections Download and Enable Role Download in the job settings control dynamic installs. Where all content is baked into signed execution environments, turning these off removes the project sync route entirely.
- Content Signature Validation Credential. Set this on the project with a GPG Public Key credential. If the signed content has been tampered with, the job does not run.
Cached roles and collections are reused between syncs; Update Revision on Launch refreshes them, with Cache Timeout limiting how often. Project syncs download Galaxy content into /tmp, so size that volume on controller and execution nodes.
Signing projects with ansible-sign
ansible-sign signs the project repository itself, which covers the playbooks, inventories and requirements files that collection signatures do not. A MANIFEST.in in the project root lists the files to protect using distlib syntax, such as recursive-include playbooks *.yml. ansible-sign project gpg-sign . writes .ansible-sign/sha256sum.txt and the detached signature .ansible-sign/sha256sum.txt.sig; ansible-sign project gpg-verify . checks both. Its exit codes separate a checksum failure (2, a file changed without re-signing) from a signature failure (3, key missing or manifest modified), which is useful for routing pipeline alerts. Include collections/requirements.yml in the manifest so a change to pins cannot pass unsigned.
Execution environment builds
In an ansible-builder version 3 definition, dependencies.galaxy takes a requirements file, dictionary or inline string. Point it at the same pinned requirements file the controller project uses. build_arg_defaults can carry ANSIBLE_GALAXY_CLI_COLLECTION_OPTS, which passes options to the collection install; keep --pre out of production definitions. A build-time ansible.cfg can be copied in through additional_build_files to point the build at your hub. On the hub side, container signing uses automationhub_create_default_container_signing_service and related variables, and clients enforce it with a signedBy entry in /etc/containers/policy.json. See the Container Image Security Guide.
Where identity fits
Every hop in this chain is authenticated by a non-human credential, and most of them are long-lived.
| Credential | Used by | Lifetime per the documentation | Control |
|---|---|---|---|
| console.redhat.com offline token | Hub rh-certified remote | Expires after 30 days of inactivity | Refresh on a schedule; owner and alert on sync failure |
| Private automation hub API token | Controller Galaxy credentials, CI, engineers | Does not expire | One per consumer, stored in a secrets manager, rotated on a calendar and on staff exit |
| Galaxy API token | Publishers of public collections | Regenerating invalidates the old token | Publish from CI only; never from laptops |
| Hub signing key | Collection and container signing services | Set by your key policy | Hold in a protected key store; separate collection and container keys |
| Project signing key | ansible-sign | Set by your key policy | Sign in CI; public half only in the GPG Public Key credential |
Red Hat documents API tokens as the way clients authenticate to automation hub, so tokens are the integration identity: treat each one as a service account with an owner and a scope. See the CI/CD Pipeline Identity Security Guide and the Code Signing Security Guide.
Rolling it out
- Inventory: Search every repository for
requirements.yml, ansible-builder definitions andansible.cfgfiles. Record each collection, its version specifier, its source and its trust tier. - Stand up the hub: Configure the
rh-certifiedandcommunityremotes with exact versions for what the inventory found, turn on approval, and configure the collection signing service. - Pin and repoint in audit mode: Change requirements files to exact versions with
sourceset to the hub. Runansible-galaxy collection verify -r requirements.yml --keyring ...in CI as a non-blocking job and fix every failure. - Pilot strict verification: For one team, set
required_valid_signature_count = +1and a hub-only server list, rebuild their execution environment and enable the Content Signature Validation Credential on their projects. - Enforce: Make verification blocking in CI, remove public Galaxy credentials from controller organisations, and decide whether to disable collection downloads at project sync.
- Roll back safely: If enforcement blocks a release, revert the pin in the requirements file or redeploy the previous execution environment tag. Do not set
disable_gpg_verifyas a fix; if an exception is unavoidable, scope it to one pipeline with an expiry date.
Small teams can stop at step 3 plus exact pins and a single trusted source; larger estates with many organisations gain most from approval, signing and per-organisation Galaxy credentials.
Detection and measurement
- Configuration drift: Alert on any commit that adds
disable_gpg_verify,ignore_certs,ignore_signature_status_codes, a public Galaxy URL or an unbounded version to a requirements file. - Verification failures: Route
ansible-galaxy collection verifyandansible-signnon-zero exits to the security queue, not only the pipeline owner. - Hub activity: Review approvals, rejections, namespace changes and token creation on private automation hub.
| Metric | Target |
|---|---|
Production requirements entries with an exact version and hub source | 100% |
| Execution environments built only from the private hub | 100% |
| Projects with a Content Signature Validation Credential | Rising to 100% of production projects |
| Hub API tokens older than the rotation period | 0 |
| Median days from upstream release to approved hub version | Tracked; agreed per trust tier |
Common failure patterns
- Floating ranges in execution environment builds: Two builds of the same image tag contain different collection versions, and nobody can say which ran during an incident.
- Public Galaxy left in the server list: A collection missing from the hub silently resolves from galaxy.ansible.com, bypassing approval.
- Signatures assumed for git installs: Teams enable keyrings and believe git-sourced collections are verified, when signature checks apply to distribution server installs only.
- Project overrides the image: A signed execution environment is undone by a project's own
collections/requirements.yml, which takes precedence at run time. - Community remote syncing everything: No version in the remote's YAML requirements, so every historical version becomes available internally.
- Tokens in shell history:
--tokenon the command line or tokens left in~/.ansible/galaxy_tokenon shared build hosts.
Framework mapping
| Control in this guide | NIST SP 800-53 Rev 5 | NIST CSF 2.0 | ATT&CK |
|---|---|---|---|
| Hub curation, approval and trust tiers | SR-3 Supply Chain Controls and Processes | GV.SC-07 | T1195.001 Compromise Software Dependencies and Development Tools |
| Exact pins and requirements inventory | SR-4 Provenance | ID.AM-02 | T1195.001 |
| GPG verification of collections and images | CM-14 Signed Components; SR-11 Component Authenticity | PR.PS-02 | T1195.002 Compromise Software Supply Chain |
ansible-sign project signing | SI-7 Software, Firmware, and Information Integrity; SI-7(15) Code Authentication | PR.PS-02 | T1195.002 |
| Disabling dynamic downloads at sync | CM-7 Least Functionality | PR.PS-02 | T1195.001 |
For the technique itself, see the MITRE ATT&CK T1195 Supply Chain Compromise guide.
Practitioner checklist
- Every production requirements entry has an exact version and a
sourcepointing at the private hub. - Transitive dependencies are listed and pinned explicitly.
server_listin production contains only approved hub repositories.required_valid_signature_countis+1or stricter and a dedicated keyring holds only the hub's collection key.disable_gpg_verify,ignore_certsand ignored status codes are absent, with alerts if added.- Hub approval is required, auto approve is off and approved collections are signed.
- The community remote lists exact versions.
- Production projects carry a Content Signature Validation Credential and
ansible-signcoverscollections/requirements.yml. - Execution environments build from the same pinned file and container images are signed and enforced through
policy.json. - Every hub, Galaxy and console token has an owner, a vault location and a rotation date.
Standards and references
- Ansible: Installing collections
- Ansible: Verifying collections
- Ansible: Ansible Configuration Settings
- Ansible: Distributing collections
- Red Hat: Managing automation content (Ansible Automation Platform 2.5)
- Ansible: ansible-sign rundown
- AWX: Projects
- Ansible Builder: Execution environment definition
Related NHI Mgmt Group resources: Ansible and AWX Security Guide, Infrastructure as Code Security Guide, SLSA and Build Provenance Guide, SBOM Guide, Secrets Management Guide.