---
# System prepended metadata

title: 'Ansible Release Management: Detailed Breakdown'

---

# Ansible Release Management: Detailed Breakdown

---

## 1) High-level picture (one-line summary)

- **ansible-core** = the engine (core runtime & modules).  
- **Ansible Community Package** = the umbrella distribution that bundles ansible-core + many Collections.  
- **Execution Environments (EEs)** = container images that package an Ansible runtime (ansible-core) and collections so users can run Ansible in a consistent container.  

These three are released on coordinated but distinct schedules; ansible-core drives the EE timelines, and the community package bundles a compatible ansible-core plus Collections.  

---

## 2) Versioning & support rules

- **Community package (Ansible)** uses **Semantic Versioning (MAJOR.MINOR.PATCH)**.  
  - Major bump = incompatible changes.  
  - Minor = backward-compatible additions.  
  - Patch = bug/security fixes.  
  - Adopted semver starting with the 2.10+ model.  

- **ansible-core** uses a different numbering (e.g., `2.11`, `2.12`).  
  - Middle digit = release number (not guaranteed backwards compatible).  
  - Patches (e.g., `2.12.1`) = bug/security fixes, released regularly.  

- **Support window**:  
  - Maintain current + X previous majors/minors (see docs).  
  - ansible-core patches ~every 4 weeks.  
  - When a new major community package is published, older majors move toward EOL.  

---

## 3) Release cadence — timeline & flow

### Development & feature merge
- New features and fixes merged to ansible-core, collections, and repos.  
- Work tracked in **roadmaps and issues**.  

### Cut ansible-core release
- Core team prepares new ansible-core (e.g., `2.13`).  
- Happens ~twice a year.  

### Maintenance window & freeze
- After new core major, collection versions freeze for community package RC.  
- **ansible-build-data** updated with collection versions.  

### Build community package
- Use **antsibull-build** to assemble from ansible-core + collections.  
- Produces wheels/tarballs.  

### Create RC(s) & run tests
- Release candidates tested with unit, integration, molecule, and packaging tests.  
- Blockers fixed → iterate RCs.  

### Publish final artifacts
- Upload wheels/sdist to **PyPI** via `twine`.  
- Push Git tags.  
- Announcements → Forum & Matrix.  

### Execution Environments rebuild
- EE images (minimal & base) rebuilt with new ansible-core + collections.  
- Published to **GHCR**.  

### Ongoing patches & backports
- Patches every ~4 weeks for core.  
- Bug/security fixes backported to supported majors.  

---

## 4) Repositories & automation

- **ansible-core repo** — engine code + roadmaps/issues.  
- **ansible-build-data** — metadata for collections + release dates.  
- **antsibull-build** — assembles community package.  
- **antsibull-changelog** — aggregates changelog fragments.  
- **images repo** — builds EE images (base & minimal).  

---

## 5) Tests & gating

- Unit tests in core & collections.  
- Integration tests & molecule scenarios.  
- End-to-end CI tests across platforms.  
- Packaging checks (wheels/sdist).  
- Changelog/lint checks.  

Release candidates only graduate after automated + manual sign-off.  

---

## 6) Execution Environments: build & release

- EE = container image with ansible-core + collections + OS pkgs.  

**Flavors:**  
- `community-ee-minimal`: ansible-core only.  
- `community-ee-base`: ansible-core + core collections (`ansible.posix`, `ansible.utils`, `ansible.windows`).  

**Build flow:**  
1. Update ansible-core / collection list.  
2. Use **ansible-builder** + Dockerfile templates.  
3. Validate (ansible-navigator, sample playbooks).  
4. Publish to GHCR with tags (e.g., `:2.18.9-1`).  

---

## 7) Changelogs, release notes, and announcements

- **antsibull-changelog** aggregates changelog fragments.  
- Release announcements posted on:  
  - **Ansible Forum** (News & Announcements).  
  - **Matrix** rooms.  
- EE releases include image tags, digests, pull commands.  

---

## 8) Roles & responsibilities

- **Core maintainers** — plan/cut ansible-core, roadmap.  
- **Release engineers** — run tooling, coordinate build-data, assemble packages, publish artifacts.  
- **Collections maintainers** — ensure compatibility & provide changelogs.  
- **Community & Release WG** — coordinate schedules, triage blockers, communicate releases.  

---

## 9) Example release timeline

| Step | Week | Action |
|------|------|--------|
| 0 | W0 | Feature freeze for ansible-core; roadmap finalized |
| 1–4 | W1–W4 | ansible-core RC builds + CI tests |
| 5 | W5 | Publish ansible-core final (e.g., `2.13`) |
| 6 | W6 | Update ansible-build-data for next community package |
| 7–8 | W7–W8 | Run antsibull-build → RC(s), CI tests |
| 9 | W9 | Publish community Ansible (e.g., `5.0.0`), push PyPI + tags |
| 10 | W10 | Rebuild/publish EE images (base/minimal) |

---

## 10) Backports, security fixes & maintenance

- ansible-core gets patches every ~4 weeks.  
- Community package & EEs follow suit.  
- Fixes are backported to supported majors.  
- Critical security fixes may trigger emergency releases.  

---

## 11) Practical commands & scripts

**Clone tooling:**
```bash
git clone https://github.com/ansible-community/ansible-build-data.git
git clone https://github.com/ansible-community/antsibull.git
git clone https://github.com/ansible-community/antsibull-changelog.git
```

- **Run an antsibull build (example — actual usage requires project-specific args):**

```
 cd antsibull
./scripts/build-ansible --from-build-data ../ansible-build-data/ansible.in --output-dir ../build
```

- (Note: antsibull has more complex scripts, uses poetry/poetry-run in repo; see repo README for exact commands.)( [GitHub](https://github.com/ansible-community/antsibull) )

### **Publish to PyPI:**

```bash
python -m pip install --upgrade twine
twine upload dist/ansible-*.whl dist/ansible-*.tar.gz
git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin vX.Y.Z
```
- **Build an EE (example using ansible-builder):**

```bash
ansible-builder build -t ghcr.io/ansible-community/community-ee-base:2.13.0-1

podman push ghcr.io/ansible-community/community-ee-base:2.13.0-1
```
-  **(Exact build steps use ansible-builder and images repo templates; see EE docs.) ([Ansible](https://docs.ansible.com/ansible/latest/getting_started_ee/index.html))**

## 12) Common pitfalls and troubleshooting

- Mismatched collection versions — include incompatible collection versions; guard by locking ansible-build-data and running CI scenarios. ([GitHub](https://github.com/ansible-community/ansible-build-data))

- Packaging failures on PyPI — packaging/metadata issues or binary wheel build failures; antsibull packaging checks and release engineers’ local install tests catch these. ([GitHub](https://github.com/ansible-community/antsibull))

- Broken RCs due to external dependencies — e.g., OS package versions in EE base images; add extra validation steps for EE images. ([GitHub](https://github.com/ansible-community/images))

## 13) How these pieces depend on each other (dependency map)
- ansible-core (engine) → base dependency for both the Community Package and EEs.


- ansible-build-data → lists Collections and exact versions used to compose the Community Package (reads from collections repos).


- antsibull-build → composes Community Package from ansible-core + ansible-build-data Collections.


- antsibull-changelog → aggregates changelogs from ansible-core + collections for release notes.


- images repo + ansible-builder → build EEs using a chosen ansible-core and collections.
``` 
- Flow:

code
 \→ test 
     \→ ansible-core release 
            \→ update build-data 
                \→ antsibull-build creates community package 
                    \→ publish to PyPI → rebuild EE images 
                        \→ publish EE images 
                            \-> announce. 
```                                
- ([GitHub](https://github.com/ansible-community/ansible-build-data))

## 14) Where to watch / join (communication & docs)

- Official docs: Release and Maintenance and Roadmaps pages for Ansible / ansible-core. ([Ansible](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html))

- GitHub: ansible-core, ansible-build-data, antsibull/antsibull-changelog, images (EE). ([GitHub](https://github.com/ansible-community/ansible-build-data))

- Community Forum (News & Announcements) and Matrix rooms (#release-management, #community, etc.) for release coordination and announcements. ([Ansible](https://forum.ansible.com/t/release-announcement-ansible-community-execution-environment-base-and-minimal-2-18-9-1/44478))

## 15) Suggested checklist for a release engineer (practical)

1. Confirm ansible-core final is built & all CI green.
1. Update ansible-build-data with Collections list & bump versions.
1. Run antsibull-build to produce RC.
1. Run full CI matrix (unit, integration, packaging, install tests).
1. Aggregate changelogs with antsibull-changelog.
1. Fix any blockers; iterate RC until green.
1. Publish final packages to PyPI; push tags & release notes.
1. Rebuild EE images; validate; push to GHCR.
1. Announce on Forum and Matrix; monitor for post-release issues and security reports. ([GitHub](https://github.com/ansible-community/antsibull))

## 16) Further reading (official resources)

- Release & Maintenance docs — Ansible docs. ([Ansible](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html))
- ansible-core Roadmaps — docs. ([Ansible](https://docs.ansible.com/ansible/latest/roadmap/ansible_core_roadmap_index.html))
- ansible-build-data — GitHub repo. ([GitHub](https://github.com/ansible-community/ansible-build-data))
- antsibull (antsibull-build) — GitHub repo & PyPI docs. ([GitHub](https://github.com/ansible-community/antsibull))
- Execution Environments (images repo & EE getting started) — GitHub + Ansible docs. ([GitHub](https://github.com/ansible-community/images))


✍️ [*Abhay Dandge*](https://www.linkedin.com/in/abhaydandge/)




