Creating OS Releases
This guide explains how to create Garden Linux major and minor OS releases.
Release Hierarchy
Garden Linux uses a three-tier release hierarchy to deliver a complete operating system.
This document is about the third tier, the OS Releases - where abstract package definitions become concrete, deployable operating system images distributed to end users.
Understanding OS Releases
Please read the OS Releases Explanation to get familiar with the concepts for the Releases.
Prerequisites
Before creating an OS release, ensure you have:
- Write access to the
gardenlinux/gardenlinuxrepository ghandghCLI tool installed and configured
Phase 0: Preparation
Step 1: Assessment of Current State
Verify that the system is ready for a release. This means all tests pass and there are no blockers for the next major release in the release workflows. Also assessing possible backports is important.
For Major Releases (on main branch):
- Is the nightly workflow green on the
mainbranch?
For Minor Releases (on release rel-* branch):
- Are there any important fixes or features that need to be backported from the
mainbranch?
Security and Quality:
- Are there any critical or highly-rated issues that need to be addressed?
- Have recent CVEs been assessed for impact?
Step 2: Check previous Tiers
Be sure to have complete Packaging and Created a APT Repository before proceeding.
Phase 1: Creating the Release
Step 1: Build Garden Linux OS
Once the APT repository is ready, we can build the OS images in tier three:
Checkout or Create Release Branch:
# For major releases, create a new release branch from main
git checkout main
git pull
git checkout -b rel-MAJOR
git push origin rel-MAJOR
# For minor releases, checkout the existing release branch
git checkout rel-MAJOR
git pullUpdate VERSION File:
# Edit the VERSION file to contain the new version
echo "MAJOR.MINOR.0" > VERSION
# Example for minor release:
echo "2150.1.0" > VERSION
# Commit the change
git add VERSION
git commit -m "Bump version to MAJOR.MINOR.0"
git push origin rel-MAJORTrigger Build Workflow:
The build process varies depending on the Garden Linux version:
For releases 2016.0.0 and later (using SemVer):
Use the manual release workflow:
# Using gh CLI:
gh workflow run "Build and publish a release" \
--ref rel-MAJOR \
-f target=release \
-f version=MAJOR.MINOR.0
# Example:
gh workflow run "Build and publish a release" \
--ref rel-2150 \
-f target=release \
-f version=2150.1.0Or via the GitHub UI:
- Go to Actions → Build and publish a release
- Click "Run workflow"
- Select the
rel-MAJORbranch - Set version to
MAJOR.MINOR.0 - Leave target
release - Leave other parameters at defaults
For older releases (1443, 1592 using non-SemVer):
Use the nightly workflow with version parameter:
# Using gh CLI:
gh workflow run nightly.yml \
--ref rel-MAJOR \
-f version=MAJOR.MINOR
# Example for 1443:
gh workflow run nightly.yml \
--ref rel-1443 \
-f version=1443.3Monitor the Build:
- Watch the workflow progress in GitHub Actions
- Verify all build jobs complete successfully
- Check that artifacts are published
Step 2: Create GitHub Release
After the build completes, create the official GitHub release page:
# Run from main branch (not the release branch!)
git checkout main
# Using gh CLI:
gh workflow run "release page" \
--ref main \
-f run_id=<BUILD-RUN-ID>
-f is_latest=true # if this is the latest major.minor.0 version
# Example:
gh workflow run "release page" \
--ref main \
-f run_id=23802291489 \
-f is_latest=true # if this is the latest major.minor.0 versionTIP
Get the "Run ID" from the URL of the "Build and publish a release" workflow run, e.g. https://github.com/gardenlinux/gardenlinux/actions/runs/23802291489
Or via the GitHub UI:
- Go to Actions → release page
- Click "Run workflow"
- Select
mainbranch - Set Build workflow run ID to
BUILD-RUN-ID(e.g.23802291489)
WARNING
Always review the generated release notes before publishing, especially the "Changes" section.
The "Changes" section lists:
- Upgraded packages in the minor release
- Fixed CVEs
This data is generated by glvd and may not be perfect. Verify:
- CVE fixes match your expectations
- Package upgrades are correctly listed
- No unexpected changes appear
Tag Manifest for Non-SemVer Releases:
WARNING
For releases that do not use semantic versioning (e.g., 1877.5), add an extra tag for compatibility with Gardener (especially for USI images).
# Example: Tag 1877.5 as 1877.5.0
oras tag ghcr.io/gardenlinux/gardenlinux:1877.5 1877.5.0Step 3: [ONLY FOR MAJOR RELEASES] Create rel-MAJOR Branch in repo
DANGER
This step only applies to new major releases, not minor releases.
Create a release branch in the gardenlinux/repo repository based on the new release tag:
cd /path/to/repo
git pull --tags
git checkout MAJOR.0.0
git checkout -b rel-MAJOR
git push -u origin rel-MAJORExample:
cd /path/to/repo
git pull --tags
git checkout 2150.0.0
git checkout -b rel-2150
git push -u origin rel-2150This branch is used for creating future minor releases of the APT repository.
Step 4: Generate CPE File
Generate the Common Platform Enumeration (CPE) file for the new release:
# Run from main branch
gh workflow run "Generate and upload CPE to a release" \
--ref main \
-f version=MAJOR.MINOR.0
# Example:
gh workflow run "Generate and upload CPE to a release" \
--ref main \
-f version=2150.1.0Or via GitHub UI:
- Go to Actions → Generate and upload CPE
- Click "Run workflow"
- Select
mainbranch - Set version to
MAJOR.MINOR.0
Step 5: Update Garden Linux Documentation
INFO
TODO: add steps on how to update the documentation
Phase 2: Post-Release Work
Verify Release Completeness
- Verify the GitHub release page is complete and accurate
- Check that all expected artifacts are attached to the release
- Confirm the CPE file was generated and uploaded
- Test installation using the new release
Notify Stakeholders
- Notify relevant teams about the new release
- Gardener OS Extension Team
- Update any documentation referencing supported versions