Pull request merge method rule public preview - feedback

[patrick-knight]

You can now enforce what merge method is available on a specific branch with the new pull request merge method rule in public preview.

Choose between Merge, Squash or Rebase and ensure only selected merge methods are supported.

Learn more in the documentation

Video example of enabling the rule

GitHubScreenShot-Arc-04-12-2024-004121.mp4

Known issues

Conflicting merge methods between the repository setting and the rule will cause merges to fail.

Feedback

We want to hear from you! Add your comments, questions, likes and dislikes below. 🔽

[DzmVasileusky]

@patrick-knight Sorry but can you share a nav path to this feature? I checked all the tabs in repository settings including General and Branches but couldn't find it.

[tdorianh]

I found it via:
Settings -> Rules -> Rulesets -> (edit or create a branch ruleset) -> Branch rules -> Require a pull request before merging -> Show additional settings -> Allowed merge methods

[patrick-knight]

@DzmVasileusky I added a video example to the post above.

[gebeto]

@freakyblack here ya go

Screen.Recording.2025-01-31.at.17.40.05.mov

[CrazyMeal]

This is great news 🥳 !
Do you have an idea about when it might be available through the rulesets API so then in Terraform provider ? 👀

[patrick-knight]

PR is going up soon to add it to the API docs, but the endpoint is live now.

      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": false,
        "required_reviewers": [],
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false,
        "automatic_copilot_code_review_enabled": false,
        "allowed_merge_methods": [
          "squash",
          "merge",
          "rebase"
        ]
      }
    }
  ],```

[ciaransweet]

Just came to ask the same! Any idea when the docs will get the update?

[ebinion]

Love it! Most of my initial use case was to manage staging versus production environments with Render, Netlify and the likes without having a CD. This should work perfectly.

[mathroule]

That's great news! Thanks for implementing this feature 🎉

This works well for one aspect of our workflow, but we still encounter a failing case.

Our workflow consists of the following steps:

1. Create a topic branch from the develop branch.
2. Merge the topic branch into the develop branch using "Squash".
3. Create a release branch from the develop branch.
4. Merge the release branch into the main branch using "Merge" (to keep Git history and keep main in sync with develop).
5. Create an apply-release-change branch from the main branch (to merge back changes from main into develop).
6. Merge the apply-release-change branch into the develop branch using "Merge".

Currently, we can only set up rule to allow "Squash" and "Merge" for merging branches into develop, regardless if it's a topic or an apply-release-change branch.

However, there is still an opportunity for developers to merge topic branch using "Merge" instead of "Squash." It would be beneficial to exclude the source branch from the ruleset, allowing us to establish rules like these:

• One ruleset that permits only "Squash" for merging into develop, except when the source branch is apply-release-change.
• Another ruleset that allows only "Merge" for merging into develop, except when the source branch is not apply-release-change (i.e. when it's a topic branch).

[nickhodaly-ud]

We have the same use case that would warrant more granular control based on the source/target branches. Most of our development follows a trunk-based approach, where ~90% of pull requests need to be squashed and merged into main. But the other ~10% of our pull requests must first be squashed and merged into a staging branch before they can make their way into main. The problem is, because our main branch ruleset only allows squash and merge, we are not able to keep a linear history when it comes time to merge our staging branch into main (Pull requests into the staging branch have already been squash + merged). If we had an option to only allow merge commits when a pull request is attempting to merge the staging branch into main that seems like it would solve our problem.

We are also using merge queues, which seems like it could result in additional complexity. If we wanted our staging -> main merges to happen via Pull Request + Merge Queue we would want the merge queue to use merge commits when the source branch is staging but squash and merge for all other source branches.

[warmfire540]

@nickhodaly-ud you would not want to squash into staging. here's what we ended up doing which works great, even though it's working around GH limitations.

Context, we have 3 branches - development, staging, production - which match our 3 environments. Any merges into these branches push to the environments.

1. devs make a branch - feature/* or bugfix/*
2. our policy FORCES them to squash this into development (keep it clean..)
3. so now dev has 3-4 features in it
4. we create a PR from dev into staging

• based on our policies, the buttons are all greyed out, a user cannot click anything
• when ready, a comment is added, or a label applied that kicks off a bot to do a fast forward into staging.

5. this is repeated for prod.

in the end of a deployment, the project branches are all linear and show that beautiful 0 | 0

[gduliscouet-ubitransport]

I think the limitation evoked here is quite common when building a software with continous deployment.

If I understood well, with the current preview we can restrict the merge method when the matching branch is either the "source" OR the "target" of the PR ? Is that right @patrick-knight ?

For me the most interesting would be to restrict the merge method when the matching branch is the "source" of the PR

---

There are few common flows I know of, but the problems usually appear when you have more than one "long-lived" branch. And they are good reasons to have more than one:

• You start by only using a develop (long-lived) branch and create some feature branches (short-lived). No versioning, as soon as a feature is merged into master it'll be deployed everywhere.
• To go a bit further you can add some tags on the develop branch. You can then deploy older versions of the code to staging or prod, but you won't be able to hotfix prod (or staging).
• Then if you want to be able to hotfix prod, you'll start creating branches. You now have 3 long-lived branches: develop, staging and prod

With this workflow we have the following use cases, and the associated merge methods:

• create a feature branch from develop and merge it into develop => "Squash and merge" my-feature into develop
• decide to update staging => "Create a merge commit" develop into staging
• decide to update prod => "Create a merge commit" staging into prod
• create a hotfix branch from prod and merge it into prod => "Squash and merge" my-hotfix into prod
• apply this hotfix (and maybe others) by "back-merging" it into staging => "Create a merge commit" prod into staging
• same for develop => "Create a merge commit" staging into develop

We use something similar to the above, and the typical human error we regularly face are:

1. someone clicked on "Squash and merge" for merging develop into staging => this is a big problem, we would need to detect it quickly and reset the staging branch to a previous commit
2. someone clicked on "Update branch" when back-merging prod into staging => this is also a big problem as it unwantedly moves prod forward
3. someone clicked on "Create a merge commit" for merging my-feature into develop => it is just a bit annoying for the git history

So the rule we would need for the above issues are:

1. when the "source" branch is long-lived, only allow to "Create a merge commit" => must have (because we never want to re-write the commits of a long-lived branch)
2. when the "source" branch is long-lived, only allow to "Create a merge commit" => must have (because it only makes sens to update the "source" branch if it is a "short-lived" branch)
3. when the "source" branch is not long-lived, don't allow to "Create a merge commit" => nice to have (for a nicer git history)

PS: I don't talk about "Rebase and merge", because it is similar to "Squash and merge". In the sense that it re-writes the commits of the source branch.

[mikkelblanne]

@patrick-knight The target branch matching was a good place to start, but we really also need source branch matching. In our case, we can make do with inclusive rules (i.e. free choice from feature/*, only merge commit from main).

We're still using git flow in a few places (develop -> release -> main), and people are now so accustomed to squash merging when doing trunk development in other repos, that they just click merge (and the button doesn't clearly show what kind of merge was performed last), also when merging i.e. release -> main. The result in this case is worse than just an unwanted merge commit in the history: Loads of conflicts later when merging main -> develop, because the commits weren't actually recorded as merged. Then we first have to clean up by force-pushing or reverting the squash commit, none of which are great for the git history.

I realize I'm not really adding anything new here, but please, I'm rooting for source branch matching to make an appearance 🙂

[Jon889]

@patrick-knight Is there any chance of this being added?

[Snailedlt]

I would like to see an option to set the default merge method per branch as well, as discussed in this discussion (or more specifically here) there are times where you want to "nudge" contributors towards using a certain merging method without enforcing it. Choosing which merge method is default is one way to do that.

[patrick-knight]

Noted and thanks for continuing to advocate for that option here. I should have been more clear in my earlier response to you in the other discussion this is a way we start addressing this problem space not nessicarily the only or final one. But I want to ensure this preview does the job and then we can iterate from here.

[DzmVasileusky]

Agree, it gives flexibility.
One of the possible use cases:
Standard feature/branch approach with develop, staging, master and feature-[n]
We want Squash be the primary (default) method for develop for cleaner git history but sometimes we need Merge commit.
Imagine you have feature-1 which wasn't merged yet and your colleague started to work on feature-2 which needs feature-1 code.
In this case you need to merge feature-1 with a Merge commit if you don't want conflicts and noise in the feature-2 PR

[dsasko]

I second this request. Having the freedom to choose any strategy whilst pushing a default one is what I would ultimately want to see. Are there any plans on adding this feature?

[komarovalexander]

HI @patrick-knight is there any plans to add default merge method to the branch? Just select it in the UI of PR by default, and use current strategy it if it is unavailable as a merge method in the settings.
For our workflow in develop branch we don't need "Require a pull request before merging" rule for all cases, but by default we would love to have "squash and merge" to keep history clean in case we create a pr - sometimes developer forgot to switch back to "squash and merge" if they did "merge" in previous pr (as result history of pr's accidentally became not so clean)

[merusso]

We want to encourage users to squash by default, but we want to continue supporting merge for certain edge cases (merging changes from one long-lived branch to another, e.g. merge release/1.0.x into release/2.0.x)

[charpeni]

There's a typo in the changelog:

The merge method rule is availible for rulesets at the repository, organization and the enterprise level.

availible -> available.

[patrick-knight]

🙈 Thanks just resolved that.

[edwardyoung]

@patrick-knight is it possible to bypass this setting to fall back to the merge methods allowed at the repo level? For example, I would want developers to only squash (set in a rule) to the dev branch while allowing members of the DevOps team to have the option to use merge or squash (set at the repo level).

[patrick-knight]

Not yet, we currently do not have bypass support built-in but once that is available you should be able to craft a rule like that.

[patrick-knight]

We just added in the ability to bypass this rule and so that should now be working as expected. Please let me know one way or the other.

[edwardyoung]

Hi @patrick-knight thanks for this! I did notice one issue when testing the bypass feature.

In my test repo settings, under Pull Requests we allow merge commits and squash merging.

I set up a branch rule targeting our default branch where the only thing checked off is "Require a pull request before merging" and the only thing set under additional settings is "Allowed merge methods" is set to Squash.

If I test this rule as is, I'm getting the expected results. On a pull request, the only merge method available is Squash. If I add myself to the bypass list, I do see both merge commits and squash merging options but if I choose merge commit, I get an error saying "The develop branch requires linear history".

Now if I disable the rule and go back to my PR, I'm able to choose merge commit without getting the error saying "The develop branch requires linear history". Would you know why this is happening? I double checked my rule and "Require linear history" is not checked off.

Thanks!

[patrick-knight]

Hey @edwardyoung,
Is there the possibility a branch protection rule is also in place on the same branch setting this requirement?

[edwardyoung]

Hi @patrick-knight ,

There is a branch protection rule but "Require linear history" is not checked off. That's the setting I would be looking for right?

[Haarolean]

Bypassing a ruleset with the merge method rule enabled doesn't work, the ruleset is still applied fully to a person included in the bypass list.
I aimed to allow everyone squash merge and rebase only for maintainers.

[patrick-knight]

That is currently a limitation that we are working in remedying

[patrick-knight]

We just added in the ability to bypass this rule and so that should now be working as expected. Please let me know one way or the other.

[Haarolean]

@patrick-knight this does work indeed now, thanks very much!

[sarah-gelt]

This is perfect for our team - we want to allow squash or merge in our dev branch, with only merge being allowed in staging and main. Now configured and looks great! 🙌

[heidimhurst]

Our exact same use case - we'd been wanting to enforce this for ages, but after a particularly bad mishap were happy to find this preview and give it a go! 🙏

[warmfire540]

how are you handling merge commits? we ask devs not to MERGE w/ the button in higher environments and instead use a command to run a fast forward. This prevents those terrible commit messages into staging/prod only

[travi]

I would like the ability to add conditions to the rule.

For the use case I'm interested in, I want to enforce a merge method that does not rewrite the history of the branch being merged when it is a (pre)release branch (in the context of a library). This would help avoid mistakes when a project values maintaining provenance between versions published to the registry, the source commits they resulted in, and the versions that follow them. In semantic-release, release channels are aligned with branches and default conventions include support for alpha and beta branches as pre-release branches.

I would like to leave the merge method flexible for normal feature contributions, but limit the merge method when the source branch being merged into the target branch that the rule is related to is a release branch. Ideally, I would supply a list of branch names to the rule that limits the merge type and would expect that the rule could be defined even if some of the named branches do not currently exist.

[patrick-knight]

Hey @travi,

Is this similar to the asks in this thread? Where depending on the source a different behavior is applied? https://github.com/orgs/community/discussions/146284#discussioncomment-11465262

[payaaam]

We have a rule that only allows "Merge" into our main branch. We are seeing an issue where this option shows "Not enabled for this repository"? There are no other repository rules that would conflict. I was wondering if we have something incorrectly configured?

[patrick-knight]

What are the pull request merge settings enabled on the repo? That might be in conflict with the rule.

https://github.com/<owner>/<repo>/settings

[payaaam]

Yep! That was it. Thank you

[gebeto]

Is it possible to configure it in the way so:

• development branch can be only merged with commit to main branch
• main branch can be only merged with commit to development branch
• any other branches can be squashed to main or development

I need this, to be able to force merge without squashing between main and development to keep whole history tracked, and be able to do some hotfix PRs with squash ability to main branch (when there are already some more changes in development branch and we need to merge hotfix right to the main branch, and then merge main branch to development to deploy that hotfix also to staging environment)

[patrick-knight]

This behavior was also mentioned in the thread here.

Currently there are no plans to address that behavior as part of this preview.

[eoudyk]

Would love for this to be added in the future, sometimes when you're going fast you might "squash and merge" a release branch instead of picking the "create a merge commit" option from the dropdown and it'd be nice to have another safe guard.

[warmfire540]

With a slew of CICD, rules and guards. We were able to work around GH.

Merged into dev only use squash, merges into higher environments the buttons are disable and they must use CD which uses fast forwarding

[a-matthew]

This is what makes this preview/feature sort of not useful in many projects. If the only difference is the choice of what's enabled for ALL branches.

This workflow presented by gebeto is a very popular GitFlow strategy. It's about habits and enforcing a structured work environment. The merge type being defaulted to the last selected option is really a bad design choice, as people may double click the same merge type (if it's allowed) across 3 entirely different branches.

One of the described 'solutions' (understandably so) in that thread is:

based on our policies, the buttons are all greyed out, a user cannot click anything
when ready, a comment is added, or a label applied that kicks off a bot to do a fast forward into staging

This is quite terrifying how complicated a very basic policy becomes. This definitely should be a very straightforward and simple process as it constitutes the core of GIT platform ecosystem... Please reconsider making it simple and granular in choice.

[xdannyrobertsx]

+1 on this ✨

[bfischler]

Was this removed from public preview?

[patrick-knight]

We moved it to be generally available last week.

[crfrolik]

Please allow us to choose the default, in addition to which options are allowed.

[mynameischawoo]

From which version of GitHub Enterprise Server is the allowed merge methods option available? Or is it still not supported in any version of GitHub Enterprise Server?
I checked the release notes up to version 3.17 in the following documentation, but I couldn’t find any mention of the allowed merge methods option:
https://docs.github.com/en/enterprise-server@3.17/admin/all-releases