Auto-sync dev branch with main after PR merges via GitHub Action

[sebastientaggart]

Problem to Fix

After a pull request is merged into the main branch, the dev branch falls behind because it doesn't contain the merge commits that GitHub creates. This requires a manual step to bring dev back in sync with main after every deployment.

Why it Matters

Developers starting new work from dev may be working from a branch that doesn't match what was just deployed. The manual sync step is easy to forget, leading to confusion and potential merge conflicts down the line.

General Approach

Add a GitHub Actions workflow that automatically fast-forwards dev to match main whenever main receives a push (i.e. after a PR merge). If a fast-forward isn't possible because dev has diverged, the workflow will open an issue to alert the team rather than silently forcing a merge.

Complexity

Verification / QA effort: moderate
The workflow needs to be tested in a real PR merge scenario to confirm it triggers correctly and pushes the updated dev branch.

Acceptance Criteria

• After merging a PR into main, the dev branch is automatically updated to match main within minutes
• If dev has diverged and cannot be fast-forwarded, an issue is opened to alert the team
• No manual intervention is required for the normal case (fast-forward succeeds)

[sebastientaggart]

Agent Implementation Notes

File to create: .github/workflows/sync-dev.yml

Approach:

• Trigger on push to main
• Use actions/checkout with fetch-depth: 0 to get full history for both branches
• Configure git credentials using the default GITHUB_TOKEN
• Attempt git merge --ff-only main on the dev branch
• If fast-forward succeeds, push dev to origin
• If fast-forward fails (dev has diverged), open an issue alerting the team about the divergence rather than forcing a merge

Key decisions:

• Fast-forward only (no merge commits or force pushes) — keeps history clean and safe
• Failure opens an issue instead of silently merging or failing — ensures visibility
• Uses GITHUB_TOKEN (no PAT needed) — simpler setup, no secret management
• Workflow needs contents: write permission to push the updated dev branch

Edge cases:

• Dev branch has unique commits not on main → ff fails → issue opened
• Concurrent pushes to main (rapid PR merges) → GitHub Actions serializes per-branch, so each run will see the latest state
• Workflow should not trigger itself (pushing dev won't re-trigger since it only watches main)

[sebastientaggart]

Resolution

A GitHub Actions workflow now automatically updates the dev branch to match main whenever a pull request is merged. If dev has diverged and can't be updated automatically, the workflow opens an issue to alert the team so it can be resolved manually.

See #119 for full technical details.