playbooks/skills/release-branch-policy/SKILL.md

Skill: release-branch-policy

Purpose

Standardize release branch policy across Cloud-Neutral Toolkit repos:

• main is the preview branch (fast iteration, integrates frequently).
• release/* branches are production release lines and must be protected.
• Updates to release/* happen via local cherry-pick by release managers (process gate).

This skill includes:

• A policy doc (this file)
• A ruleset JSON template (GitHub Rulesets API)
• A gh script to apply the ruleset to one or many repos
• A sync script to copy this skill into all local sub-repos
• A script to generate a cross-repo release manifest (for tag association)

Non-goals:

• This skill does NOT create/push release/v0.1 or tags automatically.

Policy

Branch Roles

• main: preview
  • Accepts PRs and merges normally.
  • May be ahead of production at any time.
• release/*: production
  • No force-push.
  • Require linear history.
  • Prefer "cherry-pick into release branch" as the only change mechanism (process).
  • Restrict who can update release branches to release managers (enforced via GitHub Rulesets/Branch protection UI).

“Cherry-Pick Only” Clarification

GitHub branch rules cannot reliably guarantee "only cherry-pick" as a technical constraint. We treat it as a process rule:

1. A change lands in main.
2. Release manager cherry-picks specific commits onto release/<version>.
3. Release manager pushes the updated release branch.

“No PR / No Push” Clarification

If you literally forbid both:

• PR merges to release/*, and
• any push to release/*

then the branch becomes non-updatable.

What we implement is:

• No force-push, no deletion, linear history (enforceable).
• Only release managers can update release/* (enforceable via "restrict updates" / bypass actors).
• "Cherry-pick only" (process rule).

Tags

For milestone releases like v0.1:

• Use an annotated tag named v0.1 (per-repo).
• Prefer tags on release/<version> tip.

If you need SemVer tags, follow governance: <repo>-vX.Y.Z.

Cross-Repo Tag Association

Git tags are per-repo; GitHub does not provide a first-class "one tag links all repos" concept.

We represent "release v0.1 across repos" by committing a release manifest file in the control repo, generated from local git state:

• repo name
• release branch tip SHA
• tag tip SHA

Use: skills/release-branch-policy/scripts/generate_release_manifest.sh v0.1

Ruleset Requirements (release/*)

Enforce at minimum:

• block deletion
• block force-push (non-fast-forward)
• require linear history

Optional (recommended if you have stable CI):

• require status checks
• require signed commits

Tools

1) Apply Ruleset (GitHub Rulesets)

Script: skills/release-branch-policy/scripts/apply_ruleset.sh

• Applies (create/update) a repo ruleset targeting refs/heads/release/*
• Uses gh api and a JSON payload
• Does not modify branches/tags

2) Sync Skill Into All Local Sub-Repos

Script: skills/release-branch-policy/scripts/sync_skill_to_subrepos.sh

• Copies this skill folder into each local repo under /Users/shenlan/workspaces/cloud-neutral-toolkit/*
• Skips repos without .git
• Keeps existing files unless overwritten explicitly

3) Generate Release Manifest (Cross-Repo Association)

Script: skills/release-branch-policy/scripts/generate_release_manifest.sh

• Generates releases/<version>.yaml in the current working directory (default)
• Does not push or create refs

Operator Checklist

• Confirm main is treated as preview across repos (docs + CI naming).
• Apply ruleset to every repo that has production releases.
• Document "cherry-pick only" in release runbooks.
• Verify bypass actors (release managers) in GitHub UI if needed.