ToolJet Release Cutter

Cut a release branch, bump the version, and retarget a set of feature PRs onto it.

This skill is the interactive gh-based successor to release-scripts/create-release.sh (which is milestone + raw GitHub API driven). It reuses release-scripts/bump-minor-version.sh for the version bump and the root → server/ee → frontend/ee fan-out pattern from the merge / create-pr skills.

User input: $ARGUMENTS

Inputs

Parse $ARGUMENTS. Two inputs are required — ask for whichever is missing before doing anything:

1. Edition — lts or beta.

   • lts → cut from lts-3.16
   • beta → cut from main

2. PR list — one or more PRs to retarget, as numbers or URLs. Each is either:

   • a root PR (ToolJet/ToolJet) — a "base-branch PR", or
   • a submodule PR (ToolJet/ee-server or ToolJet/ee-frontend).

   Classify each by its URL. If only a bare number is given, ask which repo it belongs to.

3. Target release branch (optional) — e.g. release/v3.20.237-lts. Pass this to add PRs to an existing release instead of cutting a new one. When omitted, the branch name is computed (Phase 1); if that branch already exists remotely, the skill switches to append mode automatically.

Fresh-cut vs. append mode. If the target release branch does not yet exist → fresh cut (Phase 1 creates it and bumps the version). If it already exists → append mode: skip the version bump and branch creation, reuse the release base PRs, and just retarget/merge the new PRs onto it (Phases 2–5). The skill is re-runnable — running it again with more PRs simply adds them.

Edition and PR line must match. A beta release only accepts PRs on the beta line (base main/develop); an lts release only accepts PRs on the lts line (base lts-3.16). A cross-line PR is a hard error — see "Validate edition vs. PR base" in Phase 2. This is checked before anything is created.

Requires the gh CLI, authenticated against ToolJet/ToolJet, ToolJet/ee-server, and ToolJet/ee-frontend.

Shell environment notes

IMPORTANT: The Bash tool runs in zsh via eval. Two constraints carried over from the merge / create-pr skills:

1. for loops cause git: command not found — never use loops. Use inline per-repo / per-PR commands.
2. Use full paths for coreutils: /usr/bin/head, /usr/bin/sed.

Set ROOT, SEE, FEE once at the top of each Bash call:

ROOT=$(git rev-parse --show-toplevel); SEE="$ROOT/server/ee"; FEE="$ROOT/frontend/ee"

Phase 1 — Create the release branch and bump the version

Skip this entire phase in append mode. First resolve $RELBR and the mode:

ROOT=$(git rev-parse --show-toplevel); BASE="<lts-3.16 for lts | main for beta>"
# $RELBR = the --target release branch if given, else the computed name (Step 1).
if git -C "$ROOT" ls-remote --heads origin "$RELBR" | /usr/bin/grep -q .; then
  echo "APPEND MODE — $RELBR exists; skip version bump + branch creation, go to Phase 2."
else
  echo "FRESH CUT — create $RELBR (Phase 1 below)."
fi

• Append mode ($RELBR exists): do not bump the version or recreate the branch. Set $NEWVER from the branch name (strip the leading release/v). Ensure the submodule release branches exist (Step 3 is still idempotent — create any missing one). Then jump to Phase 2. The release base PRs already exist and are reused in Phase 1 Step 4 / Phase 4.
• Fresh cut ($RELBR absent): run the whole phase below.

The three version files (.version, server/.version, frontend/.version) all live in the root repo, so the version bump is a root-only commit.

Step 1: Compute the bumped version and release branch name

bump-minor-version.sh bumps the patch component and preserves the suffix (-beta, -lts). Compute the same value first so we can name the branch:

ROOT=$(git rev-parse --show-toplevel)
BASE="<lts-3.16 for lts | main for beta>"
git -C "$ROOT" fetch origin "$BASE"
# Read the version from ORIGIN's base tip, not the working tree — no checkout needed,
# and immune to a stale/diverged local base branch.
VER=$(git -C "$ROOT" show "origin/$BASE:.version" | /usr/bin/head -n1)
BASEV=${VER%%-*}; SUF=${VER#*-}
IFS=. read -r MAJ MIN PAT <<< "$BASEV"
PAT=$((PAT+1))
NEWVER="${MAJ}.${MIN}.${PAT}-${SUF}"
RELBR="release/v${NEWVER}"
echo "current=$VER  new=$NEWVER  branch=$RELBR"

The suffix flows from the base branch's .version as-is (lts-3.16 → -lts, main → -beta), so RELBR already carries the right suffix — do not append another one. If $VER has no - suffix, stop and ask the user: the bump script would be a no-op.

Step 2: Create the branch in an ISOLATED WORKTREE, bump, commit, push

Do not switch the user's main checkout. It has uncommitted/untracked files (including this skill's own untracked .claude/skills/cut-release), and the base/PR branches track .claude/skills — so git checkout <base> in the main tree fails with "would lose untracked files in .claude/skills" and silently leaves you on the wrong branch, and any bump then dirties the wrong tree. Create the release branch in a throwaway worktree cut from origin/$BASE:

WT="$SCRATCH/cut-release-wt"   # a scratchpad path, NOT inside the repo
git -C "$ROOT" worktree remove --force "$WT" 2>/dev/null
git -C "$ROOT" worktree add -b "$RELBR" "$WT" "origin/$BASE"   # anchored to origin — immune to a stale local base branch
# Run the bump INSIDE the worktree. The script writes ./.version relative to CWD,
# so cwd MUST be the worktree, and the file is not +x so call it via `bash`:
( cd "$WT" && bash ./release-scripts/bump-minor-version.sh )
/usr/bin/head -1 "$WT/.version" "$WT/server/.version" "$WT/frontend/.version"   # VERIFY all three == $NEWVER before committing
git -C "$WT" commit -m "chore: bump version to ${NEWVER}" -- .version server/.version frontend/.version
git -C "$WT" push -u origin "$RELBR"

Gotchas, each learned the hard way:

• bash "$WT/release-scripts/..." with cwd still at $ROOT bumps the main tree's files (script uses ./.version). Always ( cd "$WT" && bash ./release-scripts/... ).
• Run bump-minor-version.sh without --create-branch — the branch already exists; the flag would open an unwanted chore/bump-version-* PR.
• If the three files don't show $NEWVER after the bump, stop — the script didn't run.
• Keep the worktree around until Phase 3 (root-PR merges reuse it). Remove it (git -C "$ROOT" worktree remove --force "$WT") only at the very end.

Step 3: Create matching release branches in the submodules

Create $RELBR in both submodules, cut from each submodule's own base branch (lts-3.16 for lts, main for beta). They are needed for two reasons, so create them whenever any PR (root or submodule) is in scope:

1. A submodule PR can only be re-based onto a branch that exists in its repo.
2. When a root PR is merged with the release branch, its server/ee / frontend/ee gitlink conflicts, and we resolve that pointer (Phase 3) — so the branch must exist even if no submodule PR was listed.

Operate directly on the user's $SEE / $FEE submodule checkouts (they are independent git repos — the root worktree's submodules are not initialized). First verify each is clean; this switches them off their current branch, so restore them at the end (Phase 4 cleanup).

git -C "$SEE" fetch origin "$BASE"
git -C "$SEE" checkout -b "$RELBR" "origin/$BASE"
git -C "$SEE" push -u origin "$RELBR"
git -C "$FEE" fetch origin "$BASE"
git -C "$FEE" checkout -b "$RELBR" "origin/$BASE"
git -C "$FEE" push -u origin "$RELBR"

($BASE here is the submodule's own base — lts-3.16 for lts, main for beta. Verify the submodule actually has that base branch before cutting.)

No version bump in submodules — the version files are root-only.

Step 4: Open the release base PRs — root AND each submodule

Open a release base PR ($RELBR → $BASE) in the root repo and in every submodule whose release branch has commits ahead of its base. These are the PRs the Phase 4 roster is posted on. Do it idempotently: check first, create only if missing.

# per repo (ToolJet, ee-server, ee-frontend):
EXIST=$(gh pr list --repo <owner/repo> --head "$RELBR" --state all --json number,url -q '.[0].url')
if [ -n "$EXIST" ]; then echo "exists: $EXIST"; else
  gh pr create --repo <owner/repo> --base "$BASE" --head "$RELBR" \
    --title "Release v${NEWVER}" \
    --body "Release branch for \`${NEWVER}\`. Retargeted PRs are listed in the roster comment below."
fi

• Capture each repo's release-PR number/URL for Phase 4.
• A submodule PR create can fail with "No commits between … and $RELBR" — that means the submodule's release branch is identical to its base (no PRs were retargeted into it). That's expected; skip it, don't treat it as an error.
• Cross-link: put the paired root release-PR URL in each submodule PR body (and vice-versa) so they're navigable.

Phase 2 — Expand the PR list

Build the full set of PRs to retarget. Keep a record per PR of: repo, number, headBranch, author.

For each input PR, fetch its metadata:

gh pr view <number> --repo <repo> --json number,headRefName,author,baseRefName,url

• Root PR (base-branch PR): take its headRefName, then find submodule PRs on the same head branch (ToolJet's convention is that a feature's root and submodule branches share a name — see the create-pr skill):

  gh pr list --repo ToolJet/ee-server   --head "<headBranch>" --state open --json number,headRefName,author,url
  gh pr list --repo ToolJet/ee-frontend --head "<headBranch>" --state open --json number,headRefName,author,url

  Add the root PR and any submodule PRs found to the set.
• Submodule PR: keep it as-is. Do not search for a root/base PR.

De-duplicate (a root PR and its submodule PRs may both be listed explicitly). Present the expanded set to the user before mutating anything.

Validate edition vs. PR base — HARD STOP on mismatch

A PR's current baseRefName tells which release line it belongs to: base lts-3.16 → lts, base main (or develop) → beta. A PR must match the chosen edition. Retargeting across lines is always wrong (it drags the full main↔lts divergence in as conflicts), so error out and go no further — do not create branches, change bases, or merge:

• edition lts → every PR (root and submodule) must have base lts-3.16.
• edition beta → every PR (root and submodule) must have base main / develop, i.e. not lts-3.16.

Check it before Phase 1 has created anything — ideally run Phase 2's metadata fetch first, validate, then start Phase 1. If any PR violates the rule, stop and report, e.g.:

ERROR: edition=beta but these PRs target the lts line (base lts-3.16):
  - ToolJet#18174  (feat/ext-api-v2-app-access)
  - ee-server#895  (feat/ext-api-v2-app-access)
Pick edition=lts for these PRs, or remove them. Aborting — nothing was changed.

Because this gate must fire before any mutation, reorder the run: do Phase 2 (fetch + classify + expand + validate) first, and only then Phase 1 (create branches / bump / open release PR). Nothing in Phase 1 is safe to leave behind if validation fails.

Phase 3 — Retarget and merge each PR

For each PR: change its base to $RELBR and merge $RELBR into its head branch so conflicts surface now. Order matters: process submodule PRs BEFORE their paired root PRs, because a paired root PR's gitlink must be set to the merged submodule PR-head tip (your chosen resolution). Keep a map headBranch → merged submodule tip SHA as you go.

Step 1: Change the base branch — use REST, not gh pr edit

gh pr edit --base goes through GraphQL, which returns a flaky Something went wrong while executing your query 500 (seen repeatedly right after the base branch is freshly pushed). The REST PATCH is reliable (it's what create-release.sh used):

gh api -X PATCH repos/<owner/repo>/pulls/<number> -f base="$RELBR" --jq '.base.ref'
# verify:
gh pr view <number> --repo <owner/repo> --json baseRefName -q .baseRefName