Skip to main content
  • Send to AI

Main Branch Merge Policy

Repositories that follow the feature/* → dev → main workflow enforce merge commit only when a PR is merged into main. Squash and rebase merges are disabled for that target.

Why​

Squash-merging from dev into main creates new commit SHAs on main that don't exist on dev. The content matches but the SHAs diverge, which produces two problems on every subsequent dev → main PR:

  • The "Commits" tab lists every orphaned SHA from prior releases, even though the diff only shows the new work. Reviewers see noise.
  • Tools that compare history by SHA (CI caches, deploy markers, changelog generators) treat each dev → main as a full rewrite.

Requiring merge commits preserves SHAs across both branches, keeps dev and main history in sync, and makes future dev → main PRs show only the intended diff.

Scope​

The policy applies to PRs targeting main in repositories that use a dev branch as the integration branch:

  • coniglio
  • medusa
  • farfalla (pre-registered; applies once the repo lands in the publicala org)

Repositories without a dev branch are unaffected and keep their existing merge-method settings.

Enforcement​

A GitHub organization-level ruleset named "Require merge commit on main (dev-workflow repos)" enforces the policy:

  • Target: refs/heads/main
  • Repositories: hard-coded include list above
  • Rule: pull_request with allowed_merge_methods: ["merge"]
  • Bypass actors: none

The ruleset is defined at the organization level, so it overrides any repository-level merge-method settings. Individual repositories do not need their General → Pull Requests settings changed.

Manage the ruleset at https://github.com/organizations/publicala/settings/rules.

Adding a new repo​

When another repository adopts the feature/* → dev → main workflow, add it to the ruleset's include list:

gh api /orgs/publicala/rulesets | jq '.[] | select(.name | startswith("Require merge commit")) | .id'
# → note the ruleset ID

# Pull current config, edit repository_name.include, push it back
gh api /orgs/publicala/rulesets/{id} > ruleset.json
# edit ruleset.json to append the new repo name
gh api -X PUT /orgs/publicala/rulesets/{id} --input ruleset.json

Or use the UI: Organization → Settings → Repository → Rulesets → edit the ruleset → add the repo name under "Target repositories".

  • Migration Guide for the overall GitLab → GitHub migration workflow
  • Overview for scope and motivation of the migration
X

Graph View