Collection Galaxy metadata structure

A key component of an Ansible collection is the galaxy.yml file placed in the root directory of a collection. This file contains the metadata of the collection that is used to generate a collection artifact.

Structure

The galaxy.yml file must contain the following keys in valid YAML:

Key

Comment

namespace

string 

/ 

required

The namespace of the collection.

This can be a company/brand/organization or product namespace under which all content lives.

May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with underscores or numbers and cannot contain consecutive underscores.

name

string 

/ 

required

The name of the collection.

Has the same character restrictions as namespace.

version

string 

/ 

required

The version of the collection.

Must be compatible with semantic versioning.

readme

string 

/ 

required

The path to the Markdown (.md) readme file.

This path is relative to the root of the collection.

authors

list 

/ 

required

A list of the collection’s content authors.

Can be just the name or in the format ‘Full Name <email> (url) @nicks:irc/im.site#channel’.

description

string 

A short summary description of the collection.

license

list 

Either a single license or a list of licenses for content inside of a collection.

Ansible Galaxy currently only accepts SPDX licenses

This key is mutually exclusive with license_file.

license_file

string 

The path to the license file for the collection.

This path is relative to the root of the collection.

This key is mutually exclusive with license.

tags

list 

A list of tags you want to associate with the collection for indexing/searching.

A tag name has the same character requirements as namespace and name.

dependencies

dictionary 

Collections that this collection requires to be installed for it to be usable.

The key of the dict is the collection label namespace.name.

The value is a version range specifiers.

Multiple version range specifiers can be set and are separated by ,.

repository

string 

The URL of the originating SCM repository.

documentation

string 

The URL to any online docs.

homepage

string 

The URL to the homepage of the collection/project.

issues

string 

The URL to the collection issue tracker.

build_ignore

list 


version_added: 2.10

 

A list of file glob-like patterns used to filter any files or directories that should not be included in the build artifact.

A pattern is matched from the relative path of the file or directory of the collection directory.

This uses fnmatch to match the files or directories.

Some directories and files like galaxy.yml, *.pyc, *.retry, and .git are always filtered.

Mutually exclusive with manifest

manifest

sentinel 


version_added: 2.14

 

A dict controlling use of manifest directives used in building the collection artifact.

The key directives is a list of MANIFEST.in style directives

The key omit_default_directives is a boolean that controls whether the default directives are used

Mutually exclusive with build_ignore

Examples

namespace: "namespace_name"
name: "collection_name"
version: "1.0.12"
readme: "README.md"
authors:
    - "Author1"
    - "Author2 (https://author2.example.com)"
    - "Author3 <[email protected]>"
dependencies:
    "other_namespace.collection1": ">=1.0.0"
    "other_namespace.collection2": ">=2.0.0,<3.0.0"
    "anderson55.my_collection": "*"    # note: "*" selects the highest version available
license:
    - "MIT"
tags:
    - demo
    - collection
repository: "https://www.github.com/my_org/my_collection"

See also

Developing collections

Develop or modify a collection.

Developing modules

Learn about how to write Ansible modules

Using Ansible collections

Learn how to install and use collections.

Mailing List

The development mailing list

irc.libera.chat

#ansible IRC chat channel