Collection certification onboarding

Note

Are you interested in joining the Ansible content certification program?

1. Read the Certification policy guide.
2. Not a Red Hat partner yet? Join the Partner program.

This repository aims to provide a clear set of instructions and content to help Red Hat partners:

• onboard their collections as certified content on Ansible Automation Hub
• reduce the probability of a collection version upload rejection

The provided content can be used by anyone regardless of their relationship with Red Hat.

Collection testing

Errors in Automation Hub import logs are the most common reason for collection rejection. Make sure the collection passes Galaxy-importer checks before uploading.

Running checks in GitHub Actions

To make the checks run against every pull request in your GitHub repository automatically and on a scheduled basis:

1. Copy the Ansible collection certification GitHub Actions workflow to the .github/workflows directory of your collection repository.

• Check the Actions tab on GitHub UI to make sure the workflow is running.

• Fix any failures.

  • If your collection ignores some errors by using ignore-*.txt files, make sure there are entries of allowed types only.

2. Keep a list of ansible-core versions in the Sanity job of the workflow updated when new versions of ansible-core are released:

• Subscribe to the news-for-maintainers tag on the Ansible Forum by clicking the bell button in the upper-right corner to get notified about new ansible-core versions available for testing.
• Check out the ansible-core support matrix periodically to remove EOL versions of ansible-core from your workflow's test matrix that your collection does not support.

Running checks locally

If your repository is not hosted on GitHub, please run the checks locally as described in the STEP 6: Test and lint your Ansible Collection section of the Certification workflow guide.

Check the following before uploading a collection version

Before uploading a tarball of your collection to Automation Hub:

• Consult the Ansible Certification Workflow Guide to ensure the collection meets the requirements listed in STEPS 5-7.

• Ensure that README.md in your collection contains all required sections such as Description, Installation, Support, and Changelog/Release notes.

  • To avoid rejection of your collection due to insufficient or absent sections, use the Ansible Certified Collections README Template.

  • Ensure that the Support section refers users to Automation Hub for support similar to README_template#support.

    • Additionally, for users who obtained the collection from Galaxy and have no access to Automation Hub, you can refer them for support to GitHub issues in your repository or to Ansible Forum.

• Make sure the collection passes Galaxy-importer checks on GitHub as described in the Collection testing section.

• If there are external Python dependencies in your collection, it MUST contain a requirements.txt file. Make sure:

  • No ansible or ansible-core are specified in the file.

  • To avoid conflicts with other collections requirements for users when building execution environments, the entries in the file do NOT have version caps and the versions are not fixed. This means:

    • The ONLY allowed entries are >=x.x.x or with no versions specified.
    • Entries such as <=x.x.x or ==x.x.x entries are NOT allowed. An exception to this rule applies when both the collection and its dependency are provided by the same vendor.

• Make sure your collection does not depend on other collections which are not certified on Automation Hub: the dependencies: field of the galaxy.yml file does not list any non-certified collections.

• Ensure the collection follows the Versioning and Release Strategy and specifically Semantic Versioning when determining which version to release. Practically, it means that given a version number MAJOR.MINOR.PATCH, increment the following:

  • MAJOR version (e.g., 2.y.z): when making incompatible API changes.
  • MINOR version (e.g., x.3.z: when adding features or functionality in a backward-compatible manner (e.g., adding new module options).
  • PATCH version (e.g., x.y.1) : when adding backward-compatible bug fixes or security fixes (strict).
  • The collection version must be at least 1.0.0 to be accepted.

• Ensure the collection tarball you upload contains a changelog with an entry for the version being uploaded.

  • We recommend using the antsibull-changelog tool for changelog generation.

Optional

• If you want to cover your collection with other kinds of tests (for example, unit and/or integration) to ensure your code stability, you can use the following resources:

  • Ansible Nox
  • Collection Template Workflows
  • Ansible Content Actions

• If you want to learn community best practices related to collection development and maintenance, see the Ansible community package collection requirements.

Contributing to this repository

There are a lot of good things we could recommend that partners do to improve the quality of their collections, but let's deliberately limit this repository's content to only what is required.

For exceptionally good, yet not necessary items, use the Optional section.