<< All versions

Skill v1.0.1

currentAutomated scan100/100
googlecloudplatform/cloud-foundation-fabric/release-process

+2 new

──Details
PublishedOctober 26, 2026 at 07:00 AM
Content Hashsha256:81ab2edcdcea1ae8...
Git SHA7dd5146b1cff
Bump Typepatch
Compare with v1.0.0
──Files
Files (1 file, 6.1 KB)
SKILL.md6.1 KBactive
SKILL.md · 165 lines · 6.1 KB

version: "1.0.1" name: release-process description: Guide for cutting a new release of the Cloud Foundation Fabric (CFF) repository. Use this skill when asked to create, prepare, or draft a new release.


Cloud Foundation Fabric Release Process

This skill guides maintainers through the process of cutting a new release for the Cloud Foundation Fabric (CFF) repository.

CRITICAL: Release names and tags MUST ALWAYS be prefixed with v (e.g., v55.1.0, v56.0.0).

Prerequisites

  • Permissions: You must have write/release permissions on the repository.
  • GitHub Token: A valid GitHub token (can be easily derived by running gh auth token).
  • Environment: You can run the tools using either uv (recommended) or a standard Python virtual environment with tools/requirements.txt installed.

1. Preparation

Start from the master branch and ensure you are up to date:

bash
git checkout master
git pull

Identify the latest released version by extracting it from the default-versions.tf file:

bash
LATEST_RELEASE=$(sed -n 's/^# Fabric release: //p' default-versions.tf)
echo "Latest release is: $LATEST_RELEASE"

2. Generate and Review Changelog

Run the changelog script, specifying the bump type (e.g., major, minor, patch):

bash
# Set your bump type here (major, minor, or patch)
BUMP_TYPE="minor"
# Option A: Using uv (Recommended)
uv run tools/changelog.py --release-from $LATEST_RELEASE --bump $BUMP_TYPE --write --token $(gh auth token)
# Option B: Using a standard virtual environment
./tools/changelog.py --release-from $LATEST_RELEASE --bump $BUMP_TYPE --write --token $(gh auth token)

Review the changes: Run git diff CHANGELOG.md and carefully inspect the output. Look for:

  • PRs missing labels (they will appear under a "no subsection" or similar area).
  • Weird or unclear names in PR titles.

If you find issues:

  1. Click the PR link in the diff.
  2. Manually fix the labels or title on GitHub.
  3. Re-run the changelog.py command above.
  4. Repeat until the changelog is clean.

3. Bump Versions

Once the changelog is correct, extract the newly generated release version from the top of the changelog and bump the repository versions:

bash
NEW_RELEASE=$(sed -n 's/^## \[\([^]]*\)\].* - .*/\1/p' CHANGELOG.md | head -n 1)
# Ensure it has the 'v' prefix
if [[ $NEW_RELEASE != v* ]]; then NEW_RELEASE="v$NEW_RELEASE"; fi
echo "New release is: $NEW_RELEASE"
# Option A: Using uv (Recommended)
uv run tools/versions.py --fabric-release $NEW_RELEASE --write-defaults
# Option B: Using a standard virtual environment
./tools/versions.py --fabric-release $NEW_RELEASE --write-defaults

4. Commit, Open PR, and Merge

Because master is protected and requires pull requests via the merge queue, create a branch, stage all updated files (CHANGELOG.md, default-versions.tf, default-versions.tofu, fast_version.txt, and module versions.tf/versions.tofu files), and open a PR:

bash
BRANCH_NAME="$(gh api user -q .login)/prep-$NEW_RELEASE"
git checkout -b "$BRANCH_NAME"
git add -u
git commit -m "prep $NEW_RELEASE"
git push -u origin "$BRANCH_NAME"
gh pr create \
--title "Prep $NEW_RELEASE" \
--label "on:FAST,on:modules,on:tools" \
--body "Release preparation for $NEW_RELEASE:
- \`CHANGELOG.md\`: generated with \`tools/changelog.py --release-from $LATEST_RELEASE --bump $BUMP_TYPE\`
- version strings bumped to \`$NEW_RELEASE\` with \`tools/versions.py --fabric-release $NEW_RELEASE --write-defaults\`
No functional changes; every non-CHANGELOG diff is the release string only."
# Queue the PR for auto-merge once approved and checks pass
gh pr merge --auto

Once the PR is approved and merged into master, switch back to master, pull the merged commit, and wait for the GitHub Actions workflows on master to finish successfully before proceeding to the next step:

bash
git checkout master
git pull
# Watch the latest workflow run on the master branch
gh run watch $(gh run list --branch master --limit 1 --json databaseId -q '.[0].databaseId')

5. Create the GitHub Release

You can create the release either automatically via the GitHub CLI or manually via the GitHub UI.

Option A: Automated via GitHub CLI (Recommended)

This script extracts any "BREAKING CHANGES" from the changelog and converts the heading to Title Case.

bash
# 1. Extract the section for the new release from CHANGELOG.md
# We use awk to grab everything from the new release header until the next release header
RELEASE_NOTES=$(awk "/^## \[$NEW_RELEASE\]/{flag=1; next} /^## \[v/{flag=0} flag" CHANGELOG.md)
# 2. Extract just the BREAKING CHANGES section (if any)
BREAKING_CHANGES=$(echo "$RELEASE_NOTES" | awk '/^### BREAKING CHANGES/{flag=1; print; next} /^### /{flag=0} flag')
# 3. Format breaking changes
if [ -n "$(echo "$BREAKING_CHANGES" | tr -d '[:space:]')" ]; then
# Convert "### BREAKING CHANGES" to "## Breaking Changes"
FORMATTED_BREAKING_CHANGES=$(echo "$BREAKING_CHANGES" | sed 's/^### BREAKING CHANGES/## Breaking Changes/')
echo "$FORMATTED_BREAKING_CHANGES"
fi
CRITICAL: Show the extracted and formatted breaking changes to the user and wait for their approval before proceeding to create the release.

Once approved, run the appropriate command to create the release.

If there were breaking changes:

bash
gh release create "$NEW_RELEASE" --title "$NEW_RELEASE" --generate-notes --notes "$FORMATTED_BREAKING_CHANGES"

If there were no breaking changes:

bash
gh release create "$NEW_RELEASE" --title "$NEW_RELEASE" --generate-notes

Option B: Manual via GitHub UI

Go to the GitHub Releases UI and configure the release:

  1. Tag: Create a new tag matching the new version (e.g., v56.0.0).
  2. Title: Use the exact same version string as the tag.
  3. Release Notes: Click the "Generate release notes" button.
  4. Breaking Changes: If the CHANGELOG.md contains a "BREAKING CHANGES" section for this release, copy it, paste it at the top of the generated release notes, and change the heading to "## Breaking Changes".

Click Publish release.

← v1.0.0All versions