release-please-pr-workflow

# Release-Please PR Workflow ## When to Use This Skill | Use this skill when... | Use the alternative when... | |---|---| | Iteratively merging multiple release-please PRs in a monorepo | Use `release-please-configuration` to fix the upstream config that produced them | | Resolving conflicts between sibling release PRs by closure/recreation | Use `git-conflicts` for ordinary feature-PR merge conflicts | | Coordinating sequential merges when `separate-pull-requests: true` | Use `git-fix-pr` if individual release PRs have failing CI checks | | Reducing the open release PR queue after a burst of releasable commits | Use `release-please-protection` to detect manual edits to changelog/version files | Expert knowledge for managing release-please PRs in monorepos, including batch merging, conflict handling, and iterative processing. ## Core Workflow Release-please creates separate PRs per component in monorepos (when `separate-pull-requests: true`). These PRs often need sequential merging due to shared manifest file updates. ### Iterative Merge Process 1. **List pending PRs** with status 2. **Merge clean PRs** (MERGEABLE status) 3. **Handle conflicting PRs** (close for recreation) 4. **Wait for recreation** and repeat 5. **Verify completion** when no PRs remain ## Essential Commands ### List Release PRs ```bash # List all pending release PRs gh pr list --label "autorelease: pending" # With merge status details gh pr list --label "autorelease: pending" --json number,title,mergeable,mergeStateStatus # Check specific PR status gh pr view <number> --json title,mergeable,mergeStateStatus ``` ### Check PR Mergeability | Status | Meaning | Action | |--------|---------|--------| | `CLEAN` / `MERGEABLE` | Ready to merge | Merge immediately | | `UNKNOWN` | GitHub computing | Wait 5-10 seconds, retry | | `DIRTY` / `CONFLICTING` | Has conflicts | Close and wait for recreation | ### Merge PRs ```bash # Merge single PR (squash recommended for clean history) gh pr merge <number> --squash # Merge multiple clean PRs sequentially gh pr merge 55 --squash && gh pr merge 56 --squash # Check result gh pr list --label "autorelease: pending" ``` ### Handle Conflicts ```bash # Close conflicting PRs with explanation gh pr close <number> --comment "Closing due to conflicts from merged PRs. Release-please will recreate." # Trigger workflow (if workflow_dispatch enabled) gh workflow run release-please.yml # Otherwise, wait for push trigger or new commit ``` ## Conflict Resolution Strategy ### Why Conflicts Occur Release-please PRs modify `.release-please-manifest.json` which tracks all component versions. When one PR merges: - The manifest changes - Other PRs become out of date - GitHub marks them as conflicting ### Resolution Flow ``` 1. Identify conflicting PRs ↓ 2. Close conflicting PRs with comment ↓ 3. Wait for release-please to recreate PRs (triggered by next push or workflow run) ↓ 4. New PRs appear with updated base ↓ 5. Merge clean PRs, repeat if needed ``` ### Typical Iteration Pattern ```bash # Round 1: Initial merge gh pr list --label "autorelease: pending" --json number,mergeable,mergeStateStatus # Merge CLEAN ones, note CONFLICTING ones # Round 2: Close conflicts gh pr close 45 --comment "Closing for recreation" gh pr close 46 --comment "Closing for recreation" # Wait for recreation (5-10 seconds typically) sleep 5 # Round 3: Check new PRs gh pr list --label "autorelease: pending" --json number,mergeable,mergeStateStatus # New PR numbers will appear, merge them # Repeat until no pending PRs ``` ## Complete Merge Workflow ### Full Automation Script Pattern ```bash # 1. Initial status check gh pr list --label "autorelease: pending" --json number,title,mergeable,mergeStateStatus # 2. Wait for GitHub to compute status if UNKNOWN sleep 5 gh pr list --label "autorelease: pending" --json number,title,mergeable,mergeStateStatus # 3. Merge clean PRs for pr in $(gh pr list --label "autorelease: pending" --json number,mergeStateStatus \ -q '.[] | select(.mergeStateStatus=="CLEAN") | .number'); do gh pr merge $pr --squash done # 4. Close conflicting PRs for pr in $(gh pr list --label "autorelease: pending" --json number,mergeStateStatus \ -q '.[] | select(.mergeStateStatus=="DIRTY") | .number'); do gh pr close $pr --comment "Closing for recreation after conflicts" done # 5. Wait and repeat until done sleep 10 gh pr list --label "autorelease: pending" ``` ### Interactive Workflow For complex situations, work iteratively: ```bash # Check current state gh pr list --label "autorelease: pending" --json number,title,mergeable,mergeStateStatus # Merge one by one, checking status between gh pr merge <number> --squash gh pr list --label "autorelease: pending" --json number,mergeable,mergeStateStatus # Handle UNKNOWN status by waiting sleep 5 gh pr view <number> --json mergeable,mergeStateStatus ``` ## Status Interpretation ### mergeStateStatus Values | Value | Description | Action | |-------|-------------|--------| | `CLEAN` | All checks pass, no conflicts | Merge immediately | | `UNKNOWN` | Status being computed | Wait 5-10 seconds | | `DIRTY` | Has conflicts | Close PR | | `BLOCKED` | Branch protection blocking | Check required checks | | `BEHIND` | Branch is behind base | Update branch or close | ### mergeable Values | Value | Description | |-------|-------------| | `MERGEABLE` | Can be merged | | `CONFLICTING` | Has merge conflicts | | `UNKNOWN` | Being calculated | ## Post-Merge Verification ```bash # Verify all PRs merged gh pr list --label "autorelease: pending" # Should return empty # Check new releases/tags git fetch --tags git tag --list --sort=-creatordate | head -10 # Pull latest changes git pull origin main ``` ## Common Issues ### PRs Keep Recreating **Cause:** Unreleased changes still exist for component **Check:** `git log --oneline HEAD ^<component>-v<last-version> -- <component>/` **Solution:** Merge the PR or revert the changes ### Auto-merge Not Working **Cause:** Repository doesn't have branch protection enabled **Error:** `Pull request Protected branch rules not configured for this branch` **Solution:** Use `gh pr merge --squash` without `--auto` ### Workflow Not Triggering **Cause:** release-please.yml doesn't have `workflow_dispatch` **Solution:** Wait for next push to main, or make a commit to trigger ### "Already Merged" Message **Cause:** PR was merged but GitHub CLI cache is stale **Action:** This is normal, continue with next PR ## Agentic Optimizations | Context | Command | |---------|---------| | Quick status | `gh pr list --label "autorelease: pending" --json number,mergeStateStatus` | | Batch merge | `gh pr merge N --squash && gh pr merge M --squash` | | Close with reason | `gh pr close N --comment "Conflicts"` | | Wait and check | `sleep 5 && gh pr list --label "autorelease: pending"` | ## Quick Reference ### Command Cheat Sheet | Task | Command | |------|---------| | List pending PRs | `gh pr list --label "autorelease: pending"` | | Check PR status | `gh pr view N --json mergeable,mergeStateStatus` | | Merge PR | `gh pr merge N --squash` | | Close PR | `gh pr close N --comment "reason"` | | View recent tags | `git tag --sort=-creatordate \| head -10` | | Check workflow runs | `gh run list --workflow=release-please.yml -L 5` | ### Workflow Labels | Label | Meaning | |-------|---------| | `autorelease: pending` | PR waiting to be merged | | `autorelease: tagged` | PR merged and release tagged | ## Integration with Other Skills - **release-please-configuration** - Setting up monorepo config - **release-please-protection** - Preventing manual edits to managed files - **git-commit-workflow** - Creating conventional commits that trigger releases