The Cascade Main → Dev workflow automatically forward-merges main into all open branches (dev, rc/*, beta/*, alpha/*) after every push to main. This keeps all development and pre-release branches in sync with stable releases without manual intervention.

Purpose

Sync: Ensure all open branches (dev, rc/*, beta/*, alpha/*) always include the latest stable code from main
Automation: Eliminate manual merge-forward after releases
Conflict Detection: Surface merge conflicts early via auto-created PRs
Safety: Never force-pushes or overwrites — creates PRs for manual resolution when needed

Key Features

✅ API-Only: No repository checkout required — uses Gitea REST API exclusively
✅ Idempotent: Safe to run multiple times — detects existing PRs and skips duplicates
✅ Conflict-Safe: Creates a PR for manual resolution when auto-merge fails
✅ Skip Support: Opt out per-commit with [skip cascade] or [skip ci]
✅ Deployed Org-Wide: Active on all governed (non-platform/standards) repositories

How It Works

Push to main
    ↓
Discover target branches (dev, dev/*, rc/*, beta/*, alpha/*)
    ↓ (skip if none found)
For each target branch:
    ↓
    Compare main vs branch (commits ahead)
        ↓ (skip if already in sync)
    Create PR (main → branch)
        ↓ (reuse existing if one is open)
    Check mergeable
        ├─ Clean → Auto-merge PR ✅
        └─ Conflicts → Leave PR open for manual resolution ⚠️

Step-by-Step

Branch Discovery: Queries all branches via paginated API, filters to targets matching dev, dev/*, rc/*, beta/*, alpha/*
Diff Check: For each target, queries GET /repos/{owner}/{repo}/compare/{branch}...main — if total_commits is 0, the branch is already in sync
PR Creation: Creates a PR via POST /repos/{owner}/{repo}/pulls with head: main, base: {branch}
Duplicate Prevention: Before creating, checks for existing open PRs with the same head/base
Auto-Merge: If mergeable: true, merges via POST /repos/{owner}/{repo}/pulls/{index}/merge with merge style
Conflict Handling: If mergeable: false, the PR stays open with a clear description for manual resolution

Workflow Triggers

Trigger	Condition
`push` to `main`	Every push (PR merges, bot commits, direct pushes)
`workflow_dispatch`	Manual trigger from Gitea Actions UI

Automatic Skipping

The workflow skips execution when:

The commit message contains [skip ci]
The commit message contains [skip cascade]

Configuration

Environment Variables

Variable	Default	Description
`GITEA_URL`	`https://git.mokoconsulting.tech`	Gitea instance URL
`GITEA_ORG`	`github.repository_owner`	Organization name
`GITEA_REPO`	`github.event.repository.name`	Repository name

Secrets

Secret	Required	Description
`GA_TOKEN`	Yes	Gitea API token with repo write + PR permissions

Runner

Runs on ubuntu-latest — no special runner requirements.

Conflict Resolution

When the auto-merge detects conflicts:

The workflow creates (or reuses) a PR titled chore: cascade main → {branch} ({sha}) [skip ci]
The PR body explains the conflict and links to the workflow
The workflow exits successfully (not a failure — conflicts are expected)
A developer must:
- Check out the PR locally
- Resolve conflicts
- Push the resolution
- Merge the PR

Common Conflict Sources

Version files: README.md VERSION header, updates.xml (dev has different version than main)
Changelog: Both branches modified CHANGELOG.md
CI configs: Workflow files modified independently on both branches

Skipping Cascade

Per-Commit

Add [skip cascade] to the commit message:

git commit -m "chore: version bump [skip cascade]"

Per-Push

The [skip ci] tag also prevents cascade (since the workflow checks both).

Deployment

The workflow file .gitea/workflows/cascade-dev.yml is deployed to all governed repositories (non-platform, non-standards, non-template repos).

Excluded Repositories

gitea-org-config, org-profile, gitea-private, gitea-server-setup — Platform/infra
moko-platform, moko-platform, MokoTesting — Standards repos
moko-platform-Template-*, MokoDoliProjTemplate — Template repos

Adding to a New Repository

The cascade workflow is automatically deployed by the bulk sync process. To manually add:

Copy .gitea/workflows/cascade-dev.yml from any governed repo
Ensure the repo has at least one target branch (dev, rc/*, beta/*, or alpha/*)
Ensure GA_TOKEN secret is configured

Troubleshooting

Cascade Not Triggering

Symptom: Push to main but no cascade run

Causes:

Commit message contains [skip ci] or [skip cascade]
Workflow file missing from repo
GA_TOKEN secret not configured

Solution: Check Actions tab for skipped runs; verify workflow file exists on main

Cascade Creates PR But Doesn't Merge

Symptom: PR created but left open

Cause: Merge conflicts between main and the target branch

Solution: Resolve conflicts locally and merge the PR manually

"No cascade target branches found" Message

Symptom: Workflow logs show "No cascade target branches found"

Cause: Repository doesn't have any target branches (dev, rc/*, beta/*, alpha/*)

Solution: Create a target branch from main: git checkout -b dev main && git push origin dev

Changelog

Version	Date	Changes
01.00.00	2026-05-07	Initial release — PR-based merge with conflict detection
02.00.00	2026-05-07	Cascade to all open branches (dev, rc/, beta/, alpha/*), not just dev

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version

Cascade Main → Dev Workflow

Table of Contents

Overview