OSISM release repository

Release notes published at https://osism.tech/docs/release-notes/

Overview

This repository is the central place for managing OSISM releases. It pins all component versions (container images, Ansible collections, Python packages, GitHub repositories) for each release and provides the tooling to create new releases, tag components, and generate changelogs.

Repository structure

.
├── latest/              # Current development versions (continuously updated)
│   ├── base.yml         # Core component versions
│   ├── ceph-*.yml       # Ceph-specific versions (quincy, reef, squid)
│   ├── ceph.yml         # Symlink → default Ceph version (currently ceph-reef.yml)
│   ├── openstack-*.yml  # OpenStack-specific versions (2024.1, 2024.2, 2025.1, 2025.2)
│   └── openstack.yml    # Symlink → default OpenStack version (currently openstack-2025.1.yml)
├── <VERSION>/           # Pinned release versions (e.g. 10.0.0/, 9.5.0/)
│   └── base.yml         # Frozen component versions for this release
├── next/                # SBOMs and metadata for upcoming builds
├── archive/             # Historical versions
├── etc/                 # Reference metadata
│   ├── images.yml       # Docker image name → registry path mapping
│   ├── collections.yml  # Ansible Galaxy collections
│   ├── roles.yml        # Ansible roles
│   └── changelog-repositories.yml  # Component name → GitHub source repository
├── scripts/             # Release automation scripts
│   ├── create-tags.sh
│   ├── generate-changelog-input.sh
│   └── generate-release-changelog.sh
└── src/                 # Python utilities
    ├── create-version.py
    ├── git-diff-log.py
    ├── release-notes.py
    └── remove-images-from-quay.py

Version files

latest/base.yml

The central configuration file. It tracks versions for all components of the OSISM stack:

Section	Content
manager_version	OSISM manager version identifier
ansible_version	Ansible and ansible-core versions
*_version	GitHub tag references for defaults, generics, playbooks, etc.
osism_projects	Python packages (osism, ara, docker, k3s)
docker_images	50+ container image versions
ansible_roles	External Ansible roles with commit hashes or tags
ansible_collections	Ansible Galaxy collections with semantic versions

Each version entry has a Renovate annotation comment above it (e.g. # renovate: datasource=docker depName=registry.osism.tech/osism/osism-ansible) that enables automated dependency updates.

latest/ceph-*.yml and latest/openstack-*.yml

Because OSISM supports multiple Ceph and OpenStack versions simultaneously, their versions are tracked in separate files — one per supported release stream.

Ceph files (ceph-quincy.yml, ceph-reef.yml, ceph-squid.yml):

Each file pins the versions specific to one Ceph release stream:

• ceph_version — the Ceph release name (e.g. reef)
• ceph_ansible_version — the ceph-ansible branch (e.g. stable-8.0)
• ansible_version / ansible_core_version — the Ansible versions required by that ceph-ansible branch (these can differ from the versions in base.yml)
• defaults_version, generics_version, playbooks_version — pinned component versions
• docker_images — Ceph container image versions (ceph, cephclient)

OpenStack files (openstack-2024.1.yml, openstack-2024.2.yml, openstack-2025.1.yml, openstack-2025.2.yml):

Each file pins the versions specific to one OpenStack release:

• openstack_version / openstack_previous_version — the release identifier and its predecessor (used for upgrades)
• ansible_version / ansible_core_version — the Ansible versions required for this OpenStack release
• defaults_version, generics_version, playbooks_version — pinned component versions
• docker_images — the openstackclient image version
• infrastructure_projects — list of Kolla infrastructure projects (shared across all OpenStack versions)
• openstack_projects — all OpenStack service projects with their stable branch references (e.g. stable-2025.1); some projects like gnocchi use independent versioning (e.g. stable/4.7)

Symlinks — default versions:

• ceph.yml → ceph-reef.yml — points to the current default Ceph version
• openstack.yml → openstack-2025.1.yml — points to the current default OpenStack version

These symlinks are used by consumers that do not specify a particular version and want to use the recommended default. When the default changes (e.g. after a new OpenStack release is promoted), the symlink target is updated.

Release versions (<VERSION>/) only contain base.yml. The OpenStack and Ceph files are not copied into release directories because the supported OpenStack and Ceph versions remain the same across patch releases — they are always read from latest/.

<VERSION>/base.yml

A frozen snapshot of latest/base.yml at the time of a release. Created by src/create-version.py. Does not contain Renovate annotations.

Version numbering

Component	Format	Examples
OSISM releases	Semantic versioning	9.5.0, 10.0.0, 10.0.0-rc.1
Component builds	Date-based	v0.20260322.0, 0.20260320.0
External deps	Upstream versioning	18.2.7 (Ceph), 2025.1 (OpenStack)

Release process

1. Continuous dependency updates

Renovate monitors all upstream projects and automatically creates PRs to update versions in the latest/ directory. It supports multiple datasources:

• Docker images (registry.osism.tech, Docker Hub)
• PyPI packages (ansible, osism)
• GitHub tags/releases (defaults, generics, playbooks, docker, k3s)
• Galaxy collections (osism.commons, community.docker, etc.)

Related updates are grouped (e.g. ansible + ansible-core, postgres + pgautoupgrade) to keep PRs manageable.

2. Tag creation

When component images are built and ready, create tags for the core projects:

./scripts/create-tags.sh v0.20260322.0

This creates and pushes tags in the format <project>-<version> for the five core container image projects:

• osism-ansible
• osism-kubernetes
• kolla-ansible
• ceph-ansible
• inventory-reconciler

The tags reference the current HEAD of this repository and serve as version anchors for the container image build pipelines. Existing tags can optionally be recreated.

3. Create a release version

To freeze the current latest/ state into a named release:

./src/create-version.py 10.0.0

This:

• Creates a new directory 10.0.0/
• Copies latest/base.yml (without Renovate comments)
• Queries git tags to resolve the latest versions of core container images (osism-ansible, osism-kubernetes, inventory-reconciler, kolla-ansible, ceph-ansible, kolla)
• Sets manager_version to the release name

4. Changelog generation (per-component)

Generate CHANGELOG entries from git commits using Claude:

# Auto-detect: process all tags not yet in CHANGELOG.md
./scripts/generate-changelog-input.sh --auto

# Specific tag
./scripts/generate-changelog-input.sh v0.20260322.0

# All tags from a given point onwards
./scripts/generate-changelog-input.sh --from v0.20260301.0

# Only generate input files, do not run Claude
./scripts/generate-changelog-input.sh --auto -n

The script:

1. Collects commits and diffs between consecutive tags; changelog housekeeping commits (touching only CHANGELOG.md, e.g. the release-notes PRs created by this script) are excluded and never appear in later changelogs
2. Batches them by diff size (default: 2000 lines per batch) to stay within prompt limits
3. Sends each batch to Claude for structured changelog generation
4. Merges batch results into a single entry following Keep a Changelog format
5. Auto-inserts the entry into CHANGELOG.md
6. Deletes the generated changelog-input-*.md working files again (--keep-input keeps them; with -n they are always kept)

5. Release notes generation (per release)

Generate the release notes section for a follow-up release as published at https://osism.tech/docs/release-notes/ :

# Generate the section only (written to release-notes-10.1.0.md)
./scripts/generate-release-changelog.sh 10.1.0

# Generate only the input file, review or edit it, then reuse it
# (skips the changelog fetches and the upstream analysis)
./scripts/generate-release-changelog.sh -n 10.1.0
./scripts/generate-release-changelog.sh -i release-notes-input-10.1.0.md 10.1.0

# Insert it into an existing checkout of osism.github.io
./scripts/generate-release-changelog.sh --site-dir ../osism.github.io 10.1.0

# Clone osism.github.io, insert, commit and open a pull request
./scripts/generate-release-changelog.sh --pr 10.1.0

Requires uv (fallback: a python3 with requests and PyYAML installed), the claude CLI, and an authenticated GitHub CLI (gh); with -n (input file only) neither claude nor gh is needed.

The script:

1. Diffs <version>/base.yml against the previous release
2. Fetches the CHANGELOG.md sections of all changed OSISM components for the version range (mapping: etc/changelog-repositories.yml); this includes derived components whose version is pinned in a requirements file of another component (e.g. netbox-manager in python-osism)
3. When docker_images.kolla_ansible changed, collects the upstream openstack/kolla-ansible changes pulled in by the image rebuild: the image is built from the branch of the OpenStack version in use (resolved via the kolla-ansible-v<version> tag of this repository and its latest/openstack.yml symlink), so the commit subjects and reno release notes between the build times of the two image versions are included in the input for a dedicated "OpenStack services" subsection. The added and removed downstream patches (patches/<openstack_version>) of the kolla-ansible image and, when docker_images.kolla changed, of the kolla service images are included as well: a removed patch whose change landed upstream is neither reported as a removal nor presented again as a new feature. The effective OSISM kolla defaults (osism/defaults, pinned as defaults_version) are included as a reference: configuration advice is checked against what OSISM actually sets, changes only affecting distributions other than Ubuntu are ignored, and kolla-ansible commands are written as their osism apply equivalents (there is no kolla-ansible command in OSISM)
4. Derives the recurring "images have been rebuilt" bullets deterministically from the docker_images.kolla version (never model-generated)
5. Lets Claude write an operator-focused release notes body; for entries whose changelog line alone does not tell an operator anything, Claude looks up the referenced pull requests via read-only gh pr view/ gh pr diff calls (chores and Renovate bumps are skipped). The body is sanitized deterministically before use
6. Inserts the section into docs/release-notes/osism-<major>.md of osism.github.io following the osism-10.md layout: a plain row in the release table and a ## <version> section (no date suffix), inserted before the first existing release section or directly after the release table if the page has none yet

The component CHANGELOGs are the content source: run generate-changelog-input.sh --auto in the component repositories first so that their CHANGELOG.md files cover the new component versions.

CI

Gated by Zuul with the following checks on every PR and as periodic daily jobs:

• flake8
• yamllint
• python-black

PRs are merged via squash-merge.

Tracked projects

The 12 core projects whose versions are managed in this repository:

Project	Type	Repository
osism-ansible	Container image	osism/container-image-osism-ansible
kolla-ansible	Container image	osism/container-image-kolla-ansible
ceph-ansible	Container image	osism/container-image-ceph-ansible (?)
osism-kubernetes	Container image	osism/osism-kubernetes
inventory-reconciler	Container image	osism/container-image-inventory-reconciler
osism	Python package	osism/python-osism
osism.services	Ansible collection	osism/ansible-collection-services
osism.commons	Ansible collection	osism/ansible-collection-commons
osism.playbooks	Ansible playbooks	osism/ansible-playbooks
osism.validations	Ansible collection	osism/ansible-collection-validations
manager-playbooks	Ansible playbooks	osism/ansible-playbooks-manager
defaults	Configuration	osism/defaults
generics	Configuration	osism/generics