# Red Hat Partner Collection Certification Requirements for certifying Ansible content collections on Red Hat Ansible Automation Hub. Collections must meet all requirements documented here to pass certification. # Certification requirements # Red Hat partner collection certification This site documents the requirements for certifying Ansible content collections on [Red Hat Ansible Automation Hub](https://console.redhat.com/ansible/automation-hub). Use these pages to understand what is checked during the certification process and how to prepare your collection for submission. ## Maintainers This site is maintained by the Ansible Community & Partner Engineering team at Red Hat. If you have questions about the certification requirements or need help implementing them in your collection, contact the team at [ansiblepartners@redhat.com](mailto:ansiblepartners@redhat.com). # Naming convention requirements Collection names must align with the product they support. If you are submitting a collection for the first time, verify that the collection name clearly reflects the product or technology it automates. When a product has different upstream and downstream names, use the downstream name that Red Hat customers will recognize. Collections should also follow [namespace guidelines](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_collections_creating.html#naming-your-collection) and [naming conventions](https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_in_groups.html#naming-conventions). # Collection availability requirements Collections must be publicly available in at least one of the following ways: - Published to [Ansible Galaxy](https://galaxy.ansible.com/). - Available from a public repository. # Versioning requirements Collections must follow [Semantic Versioning 2.0.0](https://semver.org/) using the **MAJOR.MINOR.PATCH** format. Collections must be at minimum version `1.0.0` to be submitted for certification. Pre-release versions, such as alpha, beta, or release candidates, are not eligible. For full details, see the [versioning strategy for Ansible certified collections](https://access.redhat.com/articles/4993781) and the [collection releasing guide](https://docs.ansible.com/projects/ansible/latest/community/collection_contributors/collection_releasing.html). ## Version components - **MAJOR**: Incompatible API changes such as breaking argspec changes, removal of plugins, or changes that alter outcomes from previous versions. - **MINOR**: New features or functionality added in a backward-compatible manner, including new modules, plugins, or roles. Also covers updates to testing matrix and metadata such as deprecation notices. - **PATCH**: Backward-compatible bug fixes, security fixes, and documentation-only changes. Patch releases must not add new features or deprecate existing functionality. Bug fixes do not require a dedicated patch release and can be included in a minor or major release. # Ansible core compatibility requirements Collections must declare `ansible-core` compatibility using the `requires_ansible` key in `meta/runtime.yml`. The value must specify a supported `ansible-core` version as a lower bound. See the [Ansible Automation Platform lifecycle](https://access.redhat.com/support/policy/updates/ansible-automation-platform#coreversion) page for currently supported `ansible-core` versions. ## Setting `requires_ansible` The `requires_ansible` value is a PEP 440 version specifier that defines which `ansible-core` versions the collection supports. The lower bound must be a supported `ansible-core` version. For example: ``` requires_ansible: ">=2.16.0" ``` An upper bound is optional: ``` requires_ansible: ">=2.16.0,<2.19.0" ``` Collections that target a higher minimum version are also acceptable. For example, if supported versions start at `2.16.0`, a collection can declare `requires_ansible: ">=2.18.0"`. ## Technology preview versions Versions of `ansible-core` released as a [Technology Preview](https://access.redhat.com/support/offerings/techpreview) are not supported for certification. Collections must not declare a Technology Preview version of `ansible-core` as the minimum value of the `requires_ansible` key. For example, `ansible-core` version 2.19 is a Technology Preview release only and collections cannot be certified with `requires_ansible >= 2.19.0`. For more information about Technology Preview versions, refer to [Current AAP and Ansible Core lifecycles](https://access.redhat.com/support/policy/updates/ansible-automation-platform#coreversion). # Licensing requirements Collections must be licensed under an [OSI-approved license](https://opensource.org/licenses/). Consult your own legal counsel for guidance on choosing a license. The license must be visible to users through at least one of the following: - The `license` or `license_file` field in `galaxy.yml`, which makes the license type visible on [Red Hat Ansible Automation Hub](https://console.redhat.com/ansible/automation-hub). - The license type stated in the README, for example Apache-2.0. - A link to the license file in the README. ## `license` and `license_file` in `galaxy.yml` The [`galaxy.yml`](https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html) file supports two mutually exclusive fields for specifying the license: - The `license` key contains a list of [SPDX license identifiers](https://spdx.org/licenses/); for example, `GPL-3.0-or-later`. - The `license_file` key specifies the path to a license file included in the collection; for example, `LICENSE`. Either the `license` or `license_file` field must be populated in `galaxy.yml`. # README requirements Collection READMEs should follow the [certified collection README template](https://github.com/ansible-collections/partner-certification-requirements/blob/main/docs/readme-template.md?plain=1) to provide a consistent experience. ## Required content At minimum, the README must include: - A clear description of the collection's purpose and use case. - A **Requirements** section listing the minimum Python version and any external dependencies. - An **Installation** section focused on installing from [Red Hat Ansible Automation Hub](https://console.redhat.com/ansible/automation-hub). - A **Changelog** or **Release notes** section that links to the collection's changelog. - A **License** section or link to the license file. ## Links All links in the README must be valid, using full URLs and markdown syntax. Do not use relative links, as READMEs are rendered outside the repository on Automation Hub. ## Installation section The installation section must not include `pip install ansible` or `pip install ansible-core` commands. Red Hat customers use execution environments to run `ansible-core` and do not install it with pip. There is no need to list `ansible-core` as a requirement because the minimum version is declared in `meta/runtime.yml`. If a collection contains validated content and it requires community packages, state those requirements in a **Requirements** section and indicate they apply when installing from Galaxy or other sources. ## Support section Collections in the `ansible` or `redhat` namespaces, or collections managed by Red Hat teams, must include a **Support** section that identifies: - Which Red Hat group maintains the collection (for example, Ansible, OpenShift, RHEL). - How customers can open support issues using the **Create issue** button on Automation Hub. The following is an example support statement: ``` This collection is maintained by Red Hat . As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the Create issue button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may be community help available on the Ansible Forum (https://forum.ansible.com/). ``` Third-party vendor collections should also include a support statement and direct Red Hat customers to open support cases via the **Create issue** button on Automation Hub. Collections published as validated content that serve both upstream (Galaxy/GitHub) and downstream (Automation Hub) distributions may direct users to the project's issue tracker or the [Ansible Forum](https://forum.ansible.com/) as the primary support channel. The [certified collection README template](https://github.com/ansible-collections/partner-certification-requirements/blob/main/docs/readme-template.md?plain=1) provides guidance on structure and content. # Changelog requirements Collections must include a changelog that documents changes between versions. The changelog must include an entry for the version being submitted for certification. The changelog can be a file in the repository, release notes on a website, or any other publicly accessible format. The collection README must reference the changelog from a **Changelog** or **Release notes** section. ## Generating changelogs The [antsibull-changelog](https://github.com/ansible-community/antsibull-changelog) tool can generate changelogs from fragment files and is widely used across Ansible collections. If a changelog tool is not practical for a given release, a summary of changes in the README under a **Changelog** or **Release notes** heading is an acceptable alternative. # Dependency requirements ## Python dependencies Collections with external Python dependencies must include them in either: - A `requirements.txt` file. - A `meta/ee-requirements.txt` file. These files are used by `ansible-builder` when creating execution environments. See [Ansible Builder - Collection-level dependencies](https://docs.ansible.com/projects/builder/en/latest/collection_metadata) for further details. Python dependencies used for collection development should not be included in the files above. Collection development dependencies should be defined in a `test-requirements.txt` file. ### No `ansible` or `ansible-core` packages The `requirements.txt` file must not list `ansible` or `ansible-core` as dependencies. Ansible Automation Platform provides `ansible-core` through execution environments. Modules and plugins have access to the `ansible` Python namespace at runtime, including `ansible.module_utils.basic`, without declaring it as a dependency. The `ansible` package is a community distribution that bundles 80+ community collections and is not supported in certified collections. References to `ansible-core` in `pyproject.toml` for collection development, such as [this example](https://github.com/ansible-collections/amazon.aws/blob/main/pyproject.toml#L33), are acceptable because they do not affect package installation. ### Version specifiers Dependency versions in `requirements.txt` must not use upper bounds or pinned versions. Use `>=` or leave the version unspecified: | Allowed | Not allowed | | ------------------ | ------------------ | | `requests` | `requests==2.31.0` | | `requests>=2.28.0` | `requests<=2.31.0` | Pinned or capped versions can cause conflicts when multiple collections in an execution environment depend on different versions of the same package. An exception applies when both the collection and its dependency are provided by the same vendor. ## Binary dependencies Collections with binary dependencies must include a `bindep.txt` file. This file is used by `ansible-builder` when creating execution environments. See [Ansible Builder - System-level Dependencies](https://docs.ansible.com/projects/builder/en/latest/collection_metadata/#system-level-dependencies) for further details. ## Collection dependencies Collection dependencies declared in `galaxy.yml` must be certified collections available on [Red Hat Ansible Automation Hub](https://console.redhat.com/ansible/automation-hub). Community collections are not permitted as dependencies in certified collections. Only validated collections can declare community collections as dependencies. # Sanity testing requirements Collections must pass `ansible-test sanity` checks for certification. ## Python boilerplate All Python files in plugins and modules must include the standard boilerplate: ``` from __future__ import absolute_import, division, print_function __metaclass__ = type ``` Missing boilerplate triggers `future-import-boilerplate` or `metaclass-boilerplate` errors. ## Sanity ignore files Sanity ignore files must only contain entries that are permitted by the Ansible Lint [sanity rules](https://docs.ansible.com/projects/lint/rules/sanity/). Invalid entries trigger `sanity[cannot-ignore]` errors and must be removed. ## Pylint checks Ansible enforces pylint rules that differ from general Python conventions: - **`disallowed-name`**: Using `_` as a variable name to capture unused return values is a common Python pattern but is not permitted in Ansible plugins and modules. See [this discussion](https://github.com/ansible/ansible/issues/79646) for background. - **`unused-import`**: Remove unused imports from plugin and module code. ## Python version support Python 2.7 is no longer supported by Red Hat Ansible Automation Platform and is not required for certified collections. To declare the minimum Python version for your collection, add a `tests/config.yml` file with a `python_requires` setting. See the [ansible.utils example](https://github.com/ansible-collections/ansible.utils/blob/main/tests/config.yml) for the expected format. ## Shell script checks The `shellcheck` sanity test flags issues in shell scripts. Address these issues where possible, or add them to your sanity ignore files if they cannot be resolved. ## Additional reference - The [partner-certification-checker](https://docs.ansible.com/projects/partner-certification-requirements/tooling/#certification-checker) provides a GitHub workflow that runs sanity and static analysis checks in CI/CD pipelines. # Static analysis requirements Certification requires collections to pass Ansible Lint scans with the [production profile](https://docs.ansible.com/projects/lint/profiles/#production). ## Rules that cannot be skipped The following rules are enforced during certification and must not appear in `skip_list` or `.ansible-lint-ignore`: - `risky-shell-pipe` - `command-instead-of-shell` - `meta-no-info` - `package-latest` - `no-handler` - `meta-runtime[unsupported-version]` - `no-changed-when` - `risky-file-permissions` - `command-instead-of-module` - `unnamed-task` Skipping these rules can mask issues that affect reliability or security in production environments. ### `meta-runtime[unsupported-version]` This rule flags collections where `requires_ansible` in `meta/runtime.yml` includes unsupported versions of `ansible-core`, even as a lower bound. Keeping `requires_ansible` current ensures that collections are validated against supported `ansible-core` versions. Enforcement may vary depending on context. Collections tightly coupled to `ansible-core` release cycles, such as those in the `ansible` and `redhat` namespaces, may have more flexibility. For partner collections, updating the `requires_ansible` to reflect currently supported `ansible-core` versions is expected as part of certification. ## Rules that should be addressed The following rules do not block certification but should be resolved in subsequent releases: - `var-spacing` - `empty-string-compare` - `role-name` - `fqcn-builtins` - `var-naming[no-role-prefix]` - `key-order` - `fqcn[action]` - `name` Violations in the [min](https://docs.ansible.com/projects/lint/profiles/#min) and [basic](https://docs.ansible.com/projects/lint/profiles/#basic) profiles generally relate to code quality and formatting and are treated similarly. ### Skipping `var-naming` Older collections frequently include `var-naming` in their skip lists. This is generally acceptable for collections past version `1.0.0`. For new collections, consider addressing the underlying naming issues instead. If you need to customize variable naming conventions, you can configure the rule in `.ansible-lint` as described in the [var-naming documentation](https://docs.ansible.com/projects/lint/rules/var-naming/#settings). ## Notable rule violations Some rule violations are particularly significant: - [ignore-errors](https://docs.ansible.com/projects/lint/rules/ignore-errors/): Can hide failures and cause unpredictable behavior. Replace `ignore_errors` directives with `failed_when` or `changed_when` error handling. - [schema](https://docs.ansible.com/projects/lint/rules/schema/): Can cause runtime failures. The `schema[meta]` violation in particular affects the integrity of collection metadata. - Missing `meta/main.yml` in roles: Every role directory must include a `meta/main.yml` file with role metadata. Missing metadata can trigger lint warnings and affects how Automation Hub displays role information. ## Ansible Lint configuration Including an `.ansible-lint` configuration file in a collection tarball is allowed for certified collections. The file can be used for downstream tooling or CI pipelines, provided it does not skip or exclude required certification checks. When configuring `.ansible-lint`, keep the following in mind: - **`skip_list`**: Must not include any of the enforced rules listed above. - **`exclude_paths`**: Must not exclude content directories such as `plugins/`, `roles/`, or `extensions/`. Excluding non-content directories such as `changelogs/`, `extensions/molecule/`, `.github/`, and `docs/` is acceptable. - **`profile`**: Must be set to `production` or omitted. ### `no-log-password` This rule is not included in any Ansible Lint profile and runs only if explicitly enabled in the `.ansible-lint` configuration. Partner teams should include `no-log-password` in `warn_list` as a security practice. ### Example `.ansible-lint` configuration .ansible-lint ``` --- # Red Hat Ansible Collection Certification .ansible-lint file # Taken from: # https://github.com/ansible-collections/partner-certification-requirements profile: production exclude_paths: - tests/integration - tests/unit - extensions/molecule - changelogs - docs - .ansible - .github warn_list: - no-log-password ``` ## Excluding directories and files from collection builds You can use the `build_ignore` section in `galaxy.yml` to exclude certain directories and files that do not contain user-facing content from collection tarballs: galaxy.yml ``` build_ignore: - tests/integration - tests/unit - extensions/molecule - changelogs - docs - collections - .github - .ansible - .tox - .venv - .agents - .claude - .vscode - .pytest_cache - .pre-commit-config.yaml ``` ## Additional reference - The [partner-certification-checker](https://docs.ansible.com/projects/partner-certification-requirements/tooling/#certification-checker) provides a GitHub workflow that runs sanity and static analysis checks in CI/CD pipelines. # Certified collection README template # Title of collection The collection title should indicate, at a high level, the purpose of the collection. > All links in the README must use full URLs and markdown syntax. Do not use relative links, as READMEs are rendered outside the repository on Red Hat Ansible Automation Hub. ## Description - Describe what the collection contains, why it is relevant, who should use it, and what it allows the user to do. ## Requirements - List any collection dependencies or Python packages. - Include additional prerequisite tasks, if applicable. - Do not include `pip install ansible` or `pip install ansible-core` commands. Red Hat does not support installing Python packages with `pip` and customers run `ansible-core` only in execution environments. - If the collection contains validated content that requires community packages, state those requirements here and indicate they apply when installing from Galaxy or other sources. ## Installation - Red Hat customers install certified collections from Red Hat Ansible Automation Hub. - Red Hat does not support installing collections from GitHub. - In addition to the boilerplate below, include any details specific to your collection, such as authentication steps required for installation. ### Installing a collection Install this collection with the Ansible Galaxy command-line tool: ``` ansible-galaxy collection install NAMESPACE.COLLECTION_NAME ``` ### Installing from a requirements file You can include this collection in a `requirements.yml` file and install it with `ansible-galaxy collection install -r requirements.yml`: ``` collections: - name: NAMESPACE.COLLECTION_NAME ``` ### Installing a specific version Use the following syntax to install version 1.0.0: ``` ansible-galaxy collection install NAMESPACE.COLLECTION_NAME:==1.0.0 ``` See [using Ansible collections](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html) for more details. ### Upgrading a collection To upgrade the collection to the latest available version, run the following command: ``` ansible-galaxy collection install NAMESPACE.COLLECTION_NAME --upgrade ``` ## Use cases - Outline three to five common use cases for the collection, with informative examples of how it has been used or how it could be used. ## Testing - List the platforms and product versions the collection supports. - Note any known limitations or workarounds. - If the collection includes example or test playbooks that users can run, mention them here. ## Contributing - This section is optional. - Include or link to contributor guidelines along with a code of conduct. - Include pointers to project tags on the [Ansible Forum](https://forum.ansible.com/) along with any other relevant contact information or communication channels. ## Support - All certified collections must include a support section that describes how customers can get help with the collection. ### Red Hat-managed collections - Collections in the `ansible` or `redhat` namespaces, or collections managed by Red Hat teams, must identify which Red Hat group maintains the collection and how customers can open support issues using the **Create issue** link on Automation Hub. - Use the following text, replacing `` with the appropriate team: ``` This collection is maintained by Red Hat . As Red Hat Ansible Certified Content, this collection is entitled to support through Ansible Automation Platform (AAP) using the **Create issue** button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may be community help available on the Ansible Forum (https://forum.ansible.com/). ``` ### Third-party vendor collections - Third-party vendor collections should include a support statement. - Support statements should be clear that Red Hat customers are entitled to open support cases via the **Create issue** button on Automation Hub. ## Release notes and roadmap - Link to the collection's release notes or changelog. - If a public roadmap is available, link to it. - Consider linking to the [Red Hat Ansible Automation Platform Life Cycle](https://access.redhat.com/support/policy/updates/ansible-automation-platform) page to help users understand the support timeline for the collection. - Private repositories can include release notes in the README or add a changelog file to the collection tarball. - Collections can add a changelog file to the docs/ directory in markdown format to display release notes in Automation Hub. ## Related information - Where available, link to general usage documentation for collections or other documentation applicable to the technology or product this collection works with. - Useful materials such as demos and case studies may be linked here as well. ## License information - The collection must use an [OSI-approved license](https://opensource.org/licenses/). - Make the license visible through the `license` field in `galaxy.yml`, the license type stated in the README, or a link to the license file in the README. - For private repositories, state the license in the README and note that the full license text is included in the downloaded collection. # Review output # Review Output Format When reviewing a collection, summarize findings in a table with one row per requirement: | Requirement | Status | Finding | | -------------------------- | ------------------- | ----------------- | | Naming Conventions | PASS / NEEDS ACTION | brief explanation | | Availability | PASS / NEEDS ACTION | brief explanation | | Versioning | PASS / NEEDS ACTION | brief explanation | | Ansible Core Compatibility | PASS / NEEDS ACTION | brief explanation | | Licensing | PASS / NEEDS ACTION | brief explanation | | README | PASS / NEEDS ACTION | brief explanation | | Changelog | PASS / NEEDS ACTION | brief explanation | | Dependencies | PASS / NEEDS ACTION | brief explanation | | Sanity Testing | PASS / NEEDS ACTION | brief explanation | | Static Analysis | PASS / NEEDS ACTION | brief explanation | | Certification Tooling | PASS / NEEDS ACTION | brief explanation |