Automate Branch Promotions with GitHub Actions

Stop manually creating PRs for branch promotions. Use these free GitHub Actions templates to automatically create staging and production PRs with semantic version prediction when CI passes.

---

TL;DR

Download free GitHub Actions templates that automatically:

• ✅ Create staging PRs when develop CI passes
• ✅ Create production PRs with semantic version prediction
• ✅ Detect breaking changes automatically
• ✅ Follow security best practices (SHA-pinned actions, minimal permissions)
• ✅ Include comprehensive pre-merge checklists

Get the free templates →

Related: Enforce semantic versioning with AI assistant rules

---

The Problem: Manual Release Overhead

Every week, your team:

1. ✋ Manually creates a PR from develop to staging
2. 📝 Manually writes release notes
3. 🧮 Manually calculates the next version number
4. 🔍 Manually checks for breaking changes
5. 😰 Hopes nothing was forgotten

This is toil. And toil doesn't scale.

Real Cost of Manual Releases

Based on our survey of 500+ engineering teams:

• 15-30 minutes per release for PR creation
• 2-4 releases per week on average
• 1-2 hours/week per team on release overhead
• 52-104 hours/year that could be spent shipping features

---

The Solution: Automated Branch Promotions

What if every time your CI passed, a perfectly formatted PR appeared automatically?

Meet Auto-Promote

# .github/workflows/auto-promote-staging.yml
on:
  workflow_run:
    workflows: ["CI"]
    branches: [develop]
    types: [completed]

That's it. When CI passes on develop, a PR to staging is created automatically.

What You Get

✅ Zero Manual Work: PRs created automatically after CI passes
✅ Smart Analysis: Counts features, fixes, and breaking changes
✅ Version Prediction: Calculates next semantic version
✅ Comprehensive Checklists: Pre-merge validation built-in
✅ Audit Trail: Clear history of what shipped when

---

How It Works

The Flow

┌──────────────────────────────────────────┐
│ 1. Developer merges PR to develop       │
└──────────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────────┐
│ 2. CI runs (tests, linting, build)      │
└──────────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────────┐
│ 3. CI passes ✅                          │
└──────────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────────┐
│ 4. 🤖 Auto-Promote workflow triggers     │
│    - Analyzes commits                    │
│    - Counts features/fixes               │
│    - Creates PR with summary             │
└──────────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────────┐
│ 5. Team reviews automated PR             │
└──────────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────────┐
│ 6. Merge → Deploy to staging             │
└──────────────────────────────────────────┘

The Staging Promotion PR

When CI passes, you automatically get:

## 🚀 Automated Staging Promotion

### 📊 Summary

- **Commits to promote:** 12
- **New features:** 3
- **Bug fixes:** 5

### 📝 Changes Included

- feat(auth): add OAuth2 support (a1b2c3d)
- fix(api): resolve race condition (e4f5g6h)
- feat(dashboard): add real-time updates (i7j8k9l)
  ...

### ✅ Pre-Merge Checklist

- [ ] All CI checks pass
- [ ] No merge conflicts
- [ ] Ready for QA testing

No manual work required. Just review and merge.

---

Semantic Versioning Made Easy

The production workflow gets even smarter:

Automatic Version Prediction

Current: v1.2.3
Commits:
  - feat: add new feature (MINOR)
  - fix: resolve bug (PATCH)
  - feat!: breaking change (MAJOR)

Prediction: v2.0.0 (MAJOR bump)

How It Works

The workflow analyzes your commits using Conventional Commits:

Commit Type	Version Impact	Example
feat!: or BREAKING CHANGE:	MAJOR bump	v1.0.0 → v2.0.0
feat:	MINOR bump	v1.0.0 → v1.1.0
fix:	PATCH bump	v1.0.0 → v1.0.1
docs:, chore:, etc.	No bump	v1.0.0 → v1.0.0

Edge Cases Handled

✅ Pre-release versions: v1.0.0-beta.1 → v1.0.0
✅ Build metadata: v1.0.0+build.123 → v1.0.0
✅ First release: v0.0.0 → v0.1.0
✅ Invalid formats: Graceful fallback with warning

Want to learn more about semantic versioning? Read our complete guide to enforcing semantic versioning with AI assistants.

---

Installation: 5 Minutes to Automation

Prerequisites

1. Branch Structure:

   • develop (or dev) - development
   • staging (or stage) - pre-production
   • main (or master) - production

2. Conventional Commits:

   feat: add new feature
   fix: resolve bug
   feat!: breaking change
   

   Need help enforcing commit format? Check out our AI assistant rules for semantic versioning.

3. Branch Protection:

   • Enable on staging and main
   • Require PR reviews
   • Require CI to pass

Step 1: Download Templates

# Create workflows directory if needed
mkdir -p .github/workflows

# Download staging promotion
curl -o .github/workflows/auto-promote-staging.yml \
  https://releaseray.com/downloads/auto-promote-staging.yml

# Download production promotion
curl -o .github/workflows/auto-promote-production.yml \
  https://releaseray.com/downloads/auto-promote-production.yml

Step 2: Customize

Open the files and update:

• Branch names (if different from develop, staging, main)
• CI workflow name (default: "CI")
• Environment URLs
• Bot email address

Step 3: Enable Permissions

1. Go to: Settings → Actions → General
2. Scroll to: Workflow permissions
3. Select: Read and write permissions
4. Click: Save

Step 4: Commit and Test

git add .github/workflows/auto-promote-*.yml
git commit -m "feat: add automated branch promotion workflows"
git push origin develop

Wait for CI to pass, then watch your first automated PR appear! 🎉

---

Real-World Example

Before Automation

Monday morning stand-up:

"Who's creating the staging PR?"
"Ugh, I'll do it. Give me 15 minutes..."
Opens GitHub, manually reviews commits, writes summary, creates PR
"Done! But I think I missed some commits..."

After Automation

Monday morning stand-up:

"PR #142 is ready for staging review"
Everyone reviews the automatically generated PR
"Looks good, merging!"

Time saved: 15 minutes per release → 30+ hours per year

---

Advanced: Customization Examples

Add Slack Notifications

- name: Notify Slack
  if: steps.check_diff.outputs.needs_promotion == 'true'
  run: |
    curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
      -H 'Content-Type: application/json' \
      -d '{"text":"🚀 Staging PR created: PR #${{ pr.number }}"}'

Add Custom Labels

labels: ["staging-promotion", "automated", "needs-qa"]

Add Assignees

await github.rest.issues.addAssignees({
  owner: context.repo.owner,
  repo: context.repo.repo,
  issue_number: pr.number,
  assignees: ['qa-lead', 'tech-lead']
});

Filter by Changed Files

# Only create PR if certain directories changed
CHANGED_DIRS=$(git diff --name-only main..staging | cut -d/ -f1 | sort -u)
if [[ "$CHANGED_DIRS" == *"src"* ]] || [[ "$CHANGED_DIRS" == *"api"* ]]; then
echo "create_pr=true" >> $GITHUB_OUTPUT
fi

---

Security Best Practices

Both templates follow GitHub Actions security best practices:

1. Minimal Permissions (Principle of Least Privilege)

permissions:
  contents: write # Only for creating branches
  pull-requests: write # Only for creating PRs
  issues: read # Only for reading issue data

Why it matters: Prevents unauthorized actions if a workflow is compromised.

Learn more: GitHub Actions Security Guide

2. SHA-Pinned Actions

# ❌ Don't use tag-based versions (can be hijacked)
uses: actions/checkout@v4

# ✅ Use SHA-pinned versions
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

Why it matters: Protects against supply chain attacks where action maintainers could push malicious code to existing tags.

3. No Secret Exposure

# ❌ Never do this
run: echo ${{ secrets.API_KEY }}

# ✅ Always do this
env:
  API_KEY: ${{ secrets.API_KEY }}
run: |
  # Use $API_KEY without exposing it

4. Branch Protection

The workflows create PRs but don't merge them. Your team still reviews and approves, maintaining human oversight.

5. Audit Trail

Every automated action is logged in GitHub Actions, providing a complete audit trail for compliance.

---

Troubleshooting

Workflow Not Triggering

Problem: Workflow doesn't run after CI passes

Solutions:

1. Check CI workflow name matches:

   gh workflow list
   

2. Verify branch name is correct

3. Check workflow permissions are enabled

Permission Denied

Problem: "Resource not accessible by integration"

Solution:

• Settings → Actions → General → Workflow permissions
• Select: "Read and write permissions"

Version Prediction Wrong

Problem: Predicted version doesn't match expected

Solutions:

1. Ensure commits use Conventional Commits format
2. Check for feat!: or BREAKING CHANGE: in messages
3. Review logs for parsing warnings

Need help with commit format? Our semantic versioning blog post includes free AI assistant rules to enforce proper commits.

---

Beyond the Templates: Advanced Tools

Just Need Version Calculation?

If you have a custom workflow but need the version calculation logic, we've extracted it as a standalone tool:

📦 Semantic Version Calculator

• Use as GitHub Action or standalone script
• Handles all edge cases (pre-release, build metadata, etc.)
• Works in any CI/CD system
• Free and open source

Learn more: Download calculate-version.sh

---

What's Next?

Want More Automation?

These templates are just the beginning. Want to take it further?

ReleaseRay provides:

• 🤖 AI-powered release notes tailored to different audiences
• 📝 Multi-channel publishing (GitHub, Intercom, Slack, Email)
• 📊 Release analytics and ROI tracking
• 🎯 Custom personas for your specific audience
• 🔄 Automated changelog generation

Try ReleaseRay Free →

Learn More

• 📚 Template documentation
• 📦 Download auto-promote-staging.yml
• 📦 Download auto-promote-production.yml
• 🔧 Download calculate-version.sh
• 📝 Conventional Commits guide
• 🎓 Semantic versioning explained
• 💬 Join our Discord community

---

Conclusion

Manual release management doesn't scale. By automating branch promotions:

✅ Save 30+ hours per year per team
✅ Reduce human error in version calculation
✅ Maintain consistent release quality
✅ Free up time for building features
✅ Create clear audit trails for compliance

The best part? These templates are free and take 5 minutes to set up.

Download the free templates →

• auto-promote-staging.yml
• auto-promote-production.yml
• calculate-version.sh

---

Related Posts

• Enforce Semantic Versioning with AI Assistant Rules
• Why Multi-Persona Release Notes Matter
• Getting Started with ReleaseRay

---

About the Author

This post was written by the ReleaseRay team. We're on a mission to automate release workflows for engineering teams worldwide.

Have questions? Contact us or join our Discord.

Found this helpful? Share it with your team! 🚀

---

Tags: github-actions ci-cd automation devops semantic-versioning release-management conventional-commits workflow-automation branch-management

---

Published by the ReleaseRay Team on November 8, 2025