Publish your first collection

Build example.hello:1.0.0, publish it to the platform hub, approve it and install it from published. This is a minimal content-distribution example; the scaffold does not implement a module or role that performs automation.

The build, import, staging-to-published move and installation were validated on the Koios test platform on 2026-11-18 using the release execution environment and username/password authentication through the internal gateway. The examples below use the public HTTPS address: configure network access and certificate trust for your deployment. The UI paths are checked against the platform UI sources; the validation performed the upload and approval through the API/CLI.

Before you start

  • Have access to Koios Automation Platform and an account allowed to create a namespace, upload to it, approve content and read the published repository. These capabilities can belong to separate users in a real review workflow.

  • Use an environment with ansible-galaxy available, such as the release execution environment or your Ansible workstation. The validated walkthrough used the release EE.

  • Ensure the client can reach the hub through the gateway. If it uses a private CA, configure that trust in the client environment; do not disable certificate verification as the normal fix.

  • Use a new working directory. If example.hello:1.0.0 already exists on your hub, inspect it or choose a namespace/version of your own rather than overwriting someone else’s example.

1. Create a namespace

Open Automation Content > Namespaces and click Create namespace. Set Name to example and Description to Example namespace of the documentation. Click Create namespace.

The collection’s namespace in galaxy.yml must match this name. Creating a platform organization with the same name does not create a collection namespace.

Details of the example namespace with its description

2. Initialize and build the collection

From your working directory:

ansible-galaxy collection init example.hello
cd example/hello

Edit the generated galaxy.yml. Keep the scaffold’s README.md; a minimal metadata example is:

namespace: example
name: hello
version: 1.0.0
readme: README.md
authors:
  - Example maintainer
description: Example collection of the documentation
license:
  - Apache-2.0
tags: []
dependencies: {}
build_ignore: []

Choose the license appropriate to content you own or are authorized to distribute. This example uses Apache-2.0. If adding roles, include a README for each role; import validation checks more than the top-level metadata.

Create or edit meta/runtime.yml as well:

---
requires_ansible: ">=2.15.0"

This field declares the Ansible version requirement of the collection. It is mandatory for this hub import. The first test upload without it failed with:

FileParserError: 'requires_ansible' in meta/runtime.yml is mandatory

Build the archive, then return to the working directory:

ansible-galaxy collection build
cd ../..

The archive is example/hello/example-hello-1.0.0.tar.gz. Keep client authentication configuration outside example/hello so that it is not packaged into a future collection build.

3. Configure the publishing client

Create ansible-publish.cfg in the working directory:

[galaxy]
server_list = koios

[galaxy_server.koios]
url = https://<platform>/api/galaxy/
username = <platform-user>

Replace the host and username. Use an account with upload permission on example. In a Bash terminal, read the password without echoing it and pass it through the server-specific variable:

unset ANSIBLE_GALAXY_SERVER_KOIOS_TOKEN
read -r -s -p 'Platform password: ' ANSIBLE_GALAXY_SERVER_KOIOS_PASSWORD
printf '\n'
export ANSIBLE_GALAXY_SERVER_KOIOS_PASSWORD
export ANSIBLE_CONFIG="$PWD/ansible-publish.cfg"

The server ID koios determines the variable name: another ID uses ANSIBLE_GALAXY_SERVER_<ID>_PASSWORD with the ID in uppercase. Do not put the password in the archive or a versioned configuration file. Username/password requires gateway Basic authentication to be enabled and an account whose password the gateway can validate.

Gateway API token alternative

A platform user’s API token is an alternative to username/password. Obtain it from API Tokens, remove username from the server configuration, unset ANSIBLE_GALAXY_SERVER_KOIOS_PASSWORD, and supply the token with ANSIBLE_GALAXY_SERVER_KOIOS_TOKEN. The token must belong to a user with the required permissions and have a scope permitting publication. Use only one authentication method for a server entry.

Gateway tokens were validated for hub access and collection installation in the earlier hub integration workflow. The example.hello publication walkthrough specifically used username/password. A token from the standalone hub’s own token endpoint does not authenticate through the platform gateway in this deployment.

4. Publish and inspect staging

With the publishing configuration selected:

ansible-galaxy collection publish example/hello/example-hello-1.0.0.tar.gz

The validated command reported successfully published and imported. Import success means the archive passed processing; it does not mean the version was approved or made available in every repository. In the tested approval configuration, example.hello:1.0.0 was present in staging and absent from published.

To upload through the UI instead, open Automation Content > Collections and click Upload collection. Select the archive in Collection file and choose staging in the repository table, then click Upload collection. Inspect its import status/logs; see Import failures.

The Upload collection form with the collection file field and the staging repository selected example.hello version 1.0.0 in the staging repository, before approval

5. Approve the version

Open Automation Content > Collection Approvals. Find example.hello, version 1.0.0, in staging, and choose Approve collection. Confirm the approval when prompted. If the deployment requires signing, the action and prerequisites differ: the UI can show Approve and sign collection. This tutorial does not configure a signing service.

Wait for the operation to finish. Verify the version in the published repository using Automation Content > Collections and the repository selector. The validated API equivalent moved the version from staging to published and returned 202; that status indicated an accepted operation, so the client waited and checked its result.

Collection Approvals with example.hello 1.0.0 from staging in Needs review status and the approve and reject actions example.hello version 1.0.0 in the published repository after approval

6. Install from published

Create a separate ansible-published.cfg in the working directory:

[galaxy]
server_list = koios

[galaxy_server.koios]
url = https://<platform>/api/galaxy/content/published/
username = <platform-user>

Use the same password environment variable for a permitted reader, or the gateway token alternative above. Select this configuration and install the exact version into an empty destination:

export ANSIBLE_CONFIG="$PWD/ansible-published.cfg"
ansible-galaxy collection install -p ./installed example.hello:1.0.0

Before approval, the validated attempt against this published endpoint did not find the version. After approval, it reported:

example.hello:1.0.0 was installed successfully

The installed collection has a MANIFEST.json under installed/ansible_collections/example/hello/. Installing the local tarball would not test approval or access to the hub; use the collection name and version against the published server for this verification.

When finished with the client session, remove the authentication variables from that shell:

unset ANSIBLE_GALAXY_SERVER_KOIOS_PASSWORD ANSIBLE_GALAXY_SERVER_KOIOS_TOKEN

Use the hub from automation controller

Follow Using collections from automation controller: add a gateway-token Ansible Galaxy/Automation Hub API Token credential to the organization’s Galaxy credentials, then reference the collection in the controller project’s collections/requirements.yml:

collections:
  - name: example.hello
    version: "1.0.0"

Update the project and inspect its result. Controller consumption through this integration was validated with another test collection containing a role; a controller job using this new minimal example.hello scaffold has not been validated. See Projects and Configuration as code before adapting the workflow to a real collection.