Join our Newsletter — 33% off our NHI Course
Home› Guides› Ansible Galaxy and Collections Supply Chain Guide: Signatures,…
Guide Software & AI Supply Chain

Ansible Galaxy and Collections Supply Chain Guide: Signatures, Pinning and Private Automation Hub

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 14 November 2026 18 min read
On this page

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-galaxy always 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_count is 1; prefix it with + so an install fails when no valid signature is found, and keep disable_gpg_verify at 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.

RouteHow it is declaredIntegrity control availableMain risk if left open
Public Galaxy (galaxy.ansible.com)ansible-galaxy collection install ns.name or requirements.yml with type: galaxyVersion pinning; GPG signatures where the server provides themNew versions and transitive dependencies resolved without review
Private automation hub[galaxy_server.<id>] entry or controller Galaxy credentialCurated sync, approval pipeline, hub-applied signaturesCommunity remote syncing every version because no version was set
Git repositorygit+https://...,<commit or tag> or type: gitPin to a commit; sign the consuming project with ansible-signBranch references that move; credentials embedded in the URI
Tarball or URLtype: file or type: urlChecksum and storage controls you build yourselfArtefacts copied between systems with no provenance record
Execution environment imagedependencies.galaxy in the ansible-builder definitionPinned requirements at build time; container image signing on the hubImages rebuilt from floating ranges, so two builds of the same tag differ
Controller project synccollections/requirements.yml in the SCM repositoryContent Signature Validation Credential; hub-only Galaxy credentialsProject 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.

SpecifierExampleWhat gets installedUse it for
None or *community.generalHighest available version at resolve timeLocal experiments only
Bounded range'>=9.0.0,<10.0.0'Highest version inside the rangeDevelopment branches that track a major version
Exact pin==9.4.0That version onlyProduction execution environments and controller projects
Exclusion'>=9.0.0,!=9.2.1'Highest version except the excluded oneBlocking a known bad release while a fix lands
Git commitgit+https://host/repo.git,<sha>The exact commitInternal collections not yet published to a hub
  • Pin transitive dependencies too: A collection's galaxy.yml declares its own dependencies with 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 source on every entry: Without it the entry defaults to the --api-server or 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_MISMATCH defaults to warning; set it to error in 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 /), token or username and password, auth_url, client_id, validate_certs and timeout. Environment variables follow ANSIBLE_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 --token is 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_certs and the per-server validate_certs exist 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_PATH defaults to galaxy_token under ANSIBLE_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 optionansible.cfg key ([galaxy])DefaultRecommended production value
--keyringgpg_keyringNot setA dedicated keyring, for example ~/.ansible/pubring.kbx, holding only your hub's collection key
--required-valid-signature-countrequired_valid_signature_count1+1, or +all where every supplied signature must validate
--ignore-signature-status-codeignore_signature_status_codesNot setEmpty; add a code such as NO_PUBKEY only with a documented reason
--disable-gpg-verifydisable_gpg_verifyFalseFalse, and alert on any change
--signatureRequirements key signaturesNot setExtra 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.gz files is out of scope for the command; --ignore-errors lets it skip those entries and process the namespace.name ones.
  • Use saved signatures in air-gapped runs: Signatures collected at install time are stored with the collection, and --offline verifies 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.

RepositoryPurposeConfiguration to set
rh-certified remoteSyncs Ansible Certified Content Collections from console.redhat.comSync URL and token from console.redhat.com; a requirements file to limit what is synced
community remoteSyncs chosen collections from Ansible GalaxyYAML requirements with an exact version per entry
validatedHolds Ansible validated contentLoaded by the RPM bundle installer by default; review what you expose
Staging (pipeline=staging)Receives uploads from anyone with namespace upload rightsRestrict namespace upload rights to named teams
Approved (pipeline=approved), e.g. PublishedContent users can view and downloadAccepts 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_approval in 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_key and automationhub_collection_signing_service_script configure a signing service, and automationhub_auto_sign_collections signs on approval. The signing script receives a file name, signs it with the key in PULP_SIGNING_KEY_FINGERPRINT and returns JSON with file and signature keys. 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:

  1. 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.
  2. 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.
  3. 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.

CredentialUsed byLifetime per the documentationControl
console.redhat.com offline tokenHub rh-certified remoteExpires after 30 days of inactivityRefresh on a schedule; owner and alert on sync failure
Private automation hub API tokenController Galaxy credentials, CI, engineersDoes not expireOne per consumer, stored in a secrets manager, rotated on a calendar and on staff exit
Galaxy API tokenPublishers of public collectionsRegenerating invalidates the old tokenPublish from CI only; never from laptops
Hub signing keyCollection and container signing servicesSet by your key policyHold in a protected key store; separate collection and container keys
Project signing keyansible-signSet by your key policySign 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

  1. Inventory: Search every repository for requirements.yml, ansible-builder definitions and ansible.cfg files. Record each collection, its version specifier, its source and its trust tier.
  2. Stand up the hub: Configure the rh-certified and community remotes with exact versions for what the inventory found, turn on approval, and configure the collection signing service.
  3. Pin and repoint in audit mode: Change requirements files to exact versions with source set to the hub. Run ansible-galaxy collection verify -r requirements.yml --keyring ... in CI as a non-blocking job and fix every failure.
  4. Pilot strict verification: For one team, set required_valid_signature_count = +1 and a hub-only server list, rebuild their execution environment and enable the Content Signature Validation Credential on their projects.
  5. Enforce: Make verification blocking in CI, remove public Galaxy credentials from controller organisations, and decide whether to disable collection downloads at project sync.
  6. 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_verify as 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 verify and ansible-sign non-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.
MetricTarget
Production requirements entries with an exact version and hub source100%
Execution environments built only from the private hub100%
Projects with a Content Signature Validation CredentialRising to 100% of production projects
Hub API tokens older than the rotation period0
Median days from upstream release to approved hub versionTracked; 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: --token on the command line or tokens left in ~/.ansible/galaxy_token on shared build hosts.

Framework mapping

Control in this guideNIST SP 800-53 Rev 5NIST CSF 2.0ATT&CK
Hub curation, approval and trust tiersSR-3 Supply Chain Controls and ProcessesGV.SC-07T1195.001 Compromise Software Dependencies and Development Tools
Exact pins and requirements inventorySR-4 ProvenanceID.AM-02T1195.001
GPG verification of collections and imagesCM-14 Signed Components; SR-11 Component AuthenticityPR.PS-02T1195.002 Compromise Software Supply Chain
ansible-sign project signingSI-7 Software, Firmware, and Information Integrity; SI-7(15) Code AuthenticationPR.PS-02T1195.002
Disabling dynamic downloads at syncCM-7 Least FunctionalityPR.PS-02T1195.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 source pointing at the private hub.
  • Transitive dependencies are listed and pinned explicitly.
  • server_list in production contains only approved hub repositories.
  • required_valid_signature_count is +1 or stricter and a dedicated keyring holds only the hub's collection key.
  • disable_gpg_verify, ignore_certs and 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-sign covers collections/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

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.

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 14 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.