Skip to content

New Ansible Releases and Freezes


Releasing new Ansible major versions and frozen releases requires some special handling. For information about the general release process, see Ansible Release Process.

Setting up for a new major release

After the release of X.0.0, it is necessary to create the directory structure for Ansible X+1.

  1. Determine the current major version and next major version

  2. Create the major version directory

    mkdir "${NEXT_MAJOR_VERSION}/"
  3. Copy over the and collection-meta.yaml files

    cp "${CURRENT_MAJOR_VERSION}/" "${CURRENT_MAJOR_VERSION}/collection-meta.yaml" \
  4. Symlink ${CURRENT_MAJOR_VERSION}.0.0's deps file to ${NEXT_MAJOR_VERSION}/ancestor.deps

    ln -sr "${CURRENT_MAJOR_VERSION}/ansible-${CURRENT_MAJOR_VERSION}.0.0.deps" \
  5. Create a stub changelog.yaml file

    cat <<EOF >${NEXT_MAJOR_VERSION}/changelog.yaml
    ancestor: ${CURRENT_MAJOR_VERSION}.0.0
    releases: {}
  6. Create a blank validate-tags-ignores file

    touch "${NEXT_MAJOR_VERSION}/validate-tags-ignores"
  7. Add the next major version to ansible-build-data's CI

    Open .github/workflows/antsibull-build.yml and the following block to the matrix:

    - name: Ansible ${NEXT_MAJOR_VERSION}
      ansible_version: ${NEXT_MAJOR_VERSION}.99.0
      ansible_major_version: ${NEXT_MAJOR_VERSION}
  8. Commit the changes

    git add "${NEXT_MAJOR_VERSION}" .github/workflows/antsibull-build.yml
  9. Submit a PR against ansible-build-data

Freeze release

Beyond the regular Ansible Release Process, X.Y.0 releases require special handling before running the release playbook.

  1. Determine the previous and the current releases

  2. Set up your Git clones and release venv as outlined in the Ansible Release Process document.

  3. Copy over the previous release's deps and galaxy files.

    cp "ansible-${PREVIOUS_VERSION}.yaml" "ansible-${VERSION}.yaml"
    cp "ansible-${PREVIOUS_VERSION}.deps" "ansible-${VERSION}.deps"
  4. Edit the current ansible version in the deps file

    sed -i "s|^_ansible_version:.*$|_ansible_version: ${VERSION}|" \
  5. Add a changelog entry for the new release

    Open ${MAJOR_VERSION}/changelog.yaml and the following block to the releases table:

          release_summary: 'Release Date: ${RELEASE_DATE}
            `Porting Guide <>`_'
        release_date: '${RELEASE_DATE}'

    The release date should be formatted as YYYY-MM-DD.

  6. Manually update specific collection versions if needed.

    In some cases, it may be necessary to update certain collections if, for example, a serious bug is found is one of the collections. In that case, open up the deps and galaxy files copied over in the step 2 and change the versions for the collections in question. Make sure that the versions in both files are consistent.

  7. Generate the tags data file

    antsibull-build validate-tags \
        --data-dir . \
        --ignores-file validate-tags-ignores \
        --output "ansible-${VERSION}-tags.yaml" \
  8. Run the the release playbook as outlined in Ansible Release Process. Make sure to use pass -e antsibull_data_reset=false to preserve the ansible-build-data modifications.