Skip to main content

Releasing (Maintainers)

This repo uses a two-branch flow to keep main stable for users:

  • beta: integration branch where feature PRs land
  • main: stable branch that should match the latest release tag

Release checklist​

1) Promote beta to main via PR​

  • Create a PR with:
    • base: main
    • compare: beta
  • Ensure required CI checks are green.
  • Merge the PR.

Release note quality depends on how you merge:

  • Squash-merging feature PRs into beta is OK.
  • Avoid squash-merging the beta -> main promotion PR. Prefer a merge commit (or rebase merge) so GitHub can produce better auto-generated release notes.

2) Run the Release workflow (manual)​

  • Go to GitHub → Actions → Release
  • Click Run workflow
  • Select:
    • patch, minor, or major
  • Run it on branch: main

What the workflow does:

  1. Creates a temporary release/vX.Y.Z branch with the version bump commit
  2. Opens a PR from that branch into main
  3. Auto-merges the PR (or waits for required checks, then merges)
  4. Creates an annotated tag vX.Y.Z on the merged commit
  5. Creates a GitHub Release for the tag
  6. Publishes artifacts (Docker / PyPI / MCPB)
  7. Opens a PR to merge main back into beta (so beta gets the bump)
  8. Auto-merges the sync PR
  9. Cleans up the temporary release branch

3) Verify release outputs​

  • Confirm a new tag exists: vX.Y.Z
  • Confirm a GitHub Release exists for the tag
  • Confirm artifacts:
    • Docker image published with version X.Y.Z
    • PyPI package published (if configured)
    • unity-mcp-X.Y.Z.mcpb attached to the GitHub Release

Required repo settings​

Branch protection (Rulesets)​

The release workflow uses PRs instead of direct pushes, so it works with strict branch protection. No bypass actors are required.

Recommended ruleset for main:

  • Require PR before merging
  • Allowed merge methods: merge, rebase (no squash for promotion PRs)
  • Required approvals: 0 (so automated PRs can merge without human review)
  • Optionally require status checks

Recommended ruleset for beta:

  • Require PR before merging
  • Allowed merge methods: squash (for feature PRs)
  • Required approvals: 0 (so the sync PR can auto-merge)

Enable auto-merge (required)​

The workflow uses gh pr merge --auto to automatically merge PRs once checks pass.

To enable:

  1. Go to Settings → General
  2. Scroll to Pull Requests
  3. Check Allow auto-merge

Without this setting, the workflow will fall back to direct merge attempts, which may fail if branch protection requires checks.

Failure modes and recovery​

Tag already exists​

The workflow fails if the computed tag already exists. Pick a different bump type or investigate why a tag already exists for that version.

Bump PR fails to merge​

If the version bump PR cannot be merged (e.g., required checks fail):

  • The workflow will fail before creating a tag.
  • Fix the issue, then either:
    • Manually merge the PR and create the tag/release, or
    • Close the PR, delete the release/vX.Y.Z branch, and re-run the workflow.

Sync PR (main -> beta) fails​

If the sync PR has merge conflicts:

  • The workflow will fail after the release is published (artifacts are already out).
  • Manually resolve conflicts in the sync PR and merge it.

Leftover release branch​

If the workflow fails mid-run, a release/vX.Y.Z branch may remain. Delete it manually before re-running:

git push origin --delete release/vX.Y.Z