Ansible Pilot

Ansible Collection Changelog with antsibull-changelog

Effortless Changelog Management for Ansible Collections with antsibull-changelog
December 4, 2023
Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons


Keeping track of changes in your Ansible collection is essential for maintaining transparency and informing users about updates, enhancements, and bug fixes. antsibull-changelog is a powerful tool that streamlines the process of managing changelogs. In this article, we’ll guide you through the steps of setting up and utilizing antsibull-changelog for your Ansible collection.


The first step is to install antsibull-changelog. Open your terminal and execute the following command:

pip install antsibull-changelog


After installing antsibull-changelog, navigate to the root directory of your Ansible collection and initialize it:

antsibull-changelog init /path/to/your/collection

This command sets up the necessary directory structure and configuration files to manage changelogs effectively.


Ensure your changelog adheres to the required format by running the linting command:

antsibull-changelog lint

The linting process helps identify and rectify any issues in your changelog.

Adding Changelog Fragment

Create a new file in the changelogs/fragments directory, such as 1.0.0.yaml. Populate this file with details about the changes made in your collection. Use the following template:

release_summary: |
  This is the first proper release of the ```` collection on 2023-12-04.
  The collection contains the ``hello-world`` filter and the ``my_role`` role.  

Replace the content within the backticks with your collection name, release date, and a brief summary of the changes.

Releasing a New Version

After adding the changelog fragment, it’s time to release the new version of your Ansible collection:

antsibull-changelog release

This command consolidates all changelog fragments, updates the version number, and creates a release entry in the main changelog file.

This is the final output in the changelogs/changelog.yaml file:

ancestor: null
      release_summary: 'This is the first proper release of the ```` collection
        on 2023-12-04.

        The collection contain the ``hello-world`` filter and the ``my_role`` role.

    - 1.0.0.yaml
    release_date: '2023-12-04'


By leveraging antsibull-changelog, you can simplify the management of Ansible collection changelogs. The tool’s straightforward commands and structure enable you to maintain organized and informative changelogs effortlessly. Enhance your workflow and provide users with valuable insights into the evolution of your Ansible collection by adopting antsibull-changelog for changelog management.

Subscribe to the YouTube channel, Medium, and Website, X (formerly Twitter) to not miss the next episode of the Ansible Pilot.


Learn the Ansible automation technology with some real-life examples in my

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

BUY the Complete PDF BOOK to easily Copy and Paste the 250+ Ansible code

Want to keep this project going? Please donate

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons
Follow me

Subscribe not to miss any new releases