🚀 Automated Environment Sync & Release Train

A GitHub Actions boilerplate for a UI-managed, "one-click" production deployment flow.

This template automates environment synchronization across main, staging, and production. It eliminates manual branch management, prevents environment drift, and generates a dynamic changelog for every production release.

🌟 Core Features

• Forward-Sync: Commits to main automatically merge into staging.
• Rolling Production PR: Commits to staging automatically create or update a persistent Pull Request targeting production.
• Dynamic Changelog: The Rolling PR automatically lists pending commits, authors, and emails.
• Hotfix Back-Sync: Any direct merges or hotfixes applied to production cascade back down to staging and main.
• Auto-Initialization: Required branches are generated automatically on your first run.

🛠️ Getting Started

1. Repository Setup

1. Click Use this template to create a new repository.
2. Ensure you have GitHub Actions enabled in your repository settings.

2. Configure the Deployment Token (Crucial)

To prevent GitHub Actions from blocking cascading workflows (infinite loop protection), you must use a Personal Access Token (PAT) instead of the default GITHUB_TOKEN.

1. Go to your GitHub Developer Settings > Personal Access Tokens.
2. Generate a new token with repo scope.
3. Go to your repository Settings > Secrets and variables > Actions.
4. Create a new repository secret named DEPLOY_PAT and paste your token.

3. Initialize Branches

You have two ways to generate the staging and production branches:

• Manual Bootstrap: Go to the Actions tab, select the 🛠️ Bootstrap Environments workflow, and click Run workflow.
• Zero-Touch: Simply push your first commit to main. The forward-sync action will detect missing branches and create them automatically.

4. Branch Protection Rules

For this flow to work securely, apply these rules in Settings > Branches:

• staging: Require status checks to pass before merging.
• production: Require a Pull Request before merging. Restrict who can push to matching branches (e.g., Tech Leads only). Allow specified actors to bypass pull request requirements for emergency hotfixes.

🏗️ Architecture & Workflows

1. Push to main (Feature Merged)
   • Action: forward-sync.yml
   • Result: Code is automatically merged into staging.
2. Push to staging (QA Ready)
   • Action: rolling-pr.yml
   • Result: A PR to production is created or updated. The title includes today's date, and the body lists all pending commits.
3. Merge to production (Release)
   • Action: back-sync.yml
   • Result: The release commit (or any emergency hotfixes made directly to production) is merged back into staging and main to prevent drift.

🚨 Disaster Recovery Playbooks

The "Partial Release" Rollback

Scenario: Three features are in the Rolling PR, but one fails QA and needs to be removed before deploying to production.

1. Locate the merged Pull Request for the broken feature on main.
2. Click the Revert button in the GitHub UI.
3. The forward-sync action will automatically merge this revert commit into staging.
4. The Rolling PR to production will update automatically, stripping out the broken code while leaving the good features intact.
5. Merge the Rolling PR safely.

Automation Failure (Merge Conflict)

Scenario: A back-sync or forward-sync fails due to a complex merge conflict.

1. The GitHub Action will fail and notify the repository owner.
2. Check out the target branch locally.
3. Merge the source branch, resolve the conflicts, and push.
4. The automation will resume standard operation on the next trigger.

"Break Glass" Manual Deploy

If GitHub Actions are down or you need to bypass the flow, add [skip ci] to your commit message to prevent the workflows from running, then handle the merges manually via the Git CLI.