Feedback: New options for controlling the default commit message when merging a pull request

[willsmythe]

We recently shipped more options for customizing the default commit message presented when merging a pull request, including using the pull request's description! The goal is more predictable, consistent, and useful commit messages for your pull requests.

How it works

From repository settings, a user with maintainer or admin access can choose the default format for commit messages produced when merging a pull request.

Learn more about configuring merge commit merging and configuring squash merging.

Thoughts?

Let us know what you think and what would make the feature more useful.

[bewuethr]

This is great, no more test / test / fix typo / ... commit messages when squashing! The only drawback I can see for the "default to pull request title and description" message is that a paragraph from the description becomes a single, potentially very long line without editing:

This PR description

becomes this log message:

I know that the PR description field is a bit special in that it's Markdown, but linebreaks are respected, so what looks good in a log message looks weirdly short-lined in the PR description.

Is it thinkable to word-wrap the description at 80 characters when converting to log message? Might not be perfect, but better than super long lines, maybe?

[adamshapiro0]

Or better yet, maybe make this configurable at a project or organization level? And have the text wrapping properly handle bulleted lists and other markdown.

We generally prefer to have the commit details be a verbatim copy of what was in the PR description. Right now, it seems to be randomly wrapping bulleted lists -- some of them wrap after ~60 chars, others don't wrap at all. For the ones that do wrap, it is not indenting the new lines correctly to match the original indent.

For some descriptions, that won't make much difference, though 60 chars does seem unnecessarily small. For more involved descriptions, this wrapping can make things much harder to read. For now, we have to undo the wrapping by hand before merging.

[brasic]

@adamshapiro0 GitHub engineer here. Would you mind sharing some example PR description lines that didn’t wrap properly when translated to a commit message? Feel free to change the phrasing to nonsense if it’s private info. You can also email it to brasic@github.com.

[adamshapiro0]

@brasic sure thing. Just sent you an email with an example, though I also just made a test PR with the description that didn't work last week and it seems to be working now. Not sure if something got fixed in production?

[bewuethr]

Hey, this (my original issue) has been fixed! Most excellent. 🚀

[SanjayVas]

Is there any way to turn the wrapping behavior off?

[kerasing]

What's the roapmap for making this part of GHE?

[willsmythe]

It's planned for the next release (3.7).

[lwhiteley]

Awesome and long awaited.

Can there also be an option for only the description?
The title can sometimes be a bit redundant when viewing the commit history

Thanks for these cool options!

[karfau]

Any plans to configure a default per organization?
We have plenty of repositories and it would be great to be able to configure the defaults when a new repo is created, or even apply those defaults to all repos that have been created before this setting was an option.

(Especially since the default is the old behavior)

[MPLew-is]

If you set the merge commit message to Default to pull request title and description, and the PR does not have a description, you can't even access the option to merge your PR and change the message until you either change the setting or add a description:

[MPLew-is]

This is what the description for that PR looks like:

[Klaitos]

Same issue here, if you put anything in the description it fix the issue for information.

[MPLew-is]

This appears to be fixed now.

[Mina012015]

نفس المشكلة هنا ، إذا وضعت أي شيء في الوصف ، فسيتم إصلاح المشكلة للحصول على المعلومات.

ع

[tiit-clarifai]

Our PR template contains markdown comments to provide instructions on what to write in the description. These are not visible in the rendered view so are often left intact by developers, but are undesirable noise in the plaintext commit message.

Would you consider adding an option to omit comments from the PR description when used as the default commit message?

For example, let's say you have the following PR description:

<!-- Please include a summary of the changes proposed in this pull request. -->
This PR updates our Petshop API client to version 2.0.

<!-- If there is a related issue to this PR, then reference it here. -->
Fixes #1234

<!-- ### Notes -->
<!-- If you have any additional notes, then uncomment the section above and write them here. -->

Enabling the option would generate the following commit message when used with Pull request title and description:

Pull Request Title (#5678)

This PR updates our Petshop API client to version 2.0.

Fixes #12345

[rmacklin]

If a commit message includes a code snippet which contains an HTML comment, ideally the code snippet would not be modified. (In other words, I think we would only want to omit HTML comments that are not part of a code snippet.)

[willsmythe]

Good suggestion. We have an issue tracking this internally.

[kriskowal]

Where can the public track progress? Thank you, omitting guidance comments would be very fine.

[moldovan-clarifai]

@willsmythe any update on this? at the time of writing, there are 44 up-votes.

[theprivileges]

This is a feature that would save us a lot of time. Right now we have to manually remove these HTML comments from our template before merging with pull request title and description.

[jplatte]

It would be really nice to be able to just set a template. The dropdown options right now really aren't self-explanatory. None of them suggest the PR number will be included, which I expected from the blog post title I could finally get rid of…

[willsmythe]

Templates is something we want to support in the future, just didn't make the cut for this initial wave of improvements.

[zane131]

It's almost been two years. Any outlook on this?

[brandonbirdj]

When selecting option to use pull request title it appears to take the original title from when the pull request was created. I would expect it to take the PR title at the time of merging.

For example many actions such as https://github.com/marketplace/actions/pull-request-ticket-check-action automatically update the PR title.

[willsmythe]

Did you switch the new repo-level setting to something other than the default commit message format? The default commit message format for squash merge is the commit message (if the PR contains only 1 commit), which is sometimes the same as the PR title, but obviously can be different.

[brandonbirdj]

I've updated to clarify that this finding is for when the new setting of using pull request title is used.

[EricStG]

Is it possible to configure this via .github/settings.yml? I can't find any doc for it

[bewuethr]

Isn't that file provided/read by a third-party app?

[EricStG]

It is, my bad!

[bewuethr]

tl;dr: It would be nice to be able to select defaults based on PR author.

---

My use case is pretty much to optimize for the case where the merger doesn't edit the merge commit message at all. Using "Default to pull request title and description" gets us pretty far for that, and it can be improved with linters running on the PR description and similar.

However, one case that isn't covered and leads to an ugly default is dependabot PRs. The description on a dependabot PR is very, very long, and makes for a terrible commit message.

I'm not sure what a great default could be. Maybe the ability to set the behaviour depending on the PR author? If opened by dependabot, then use "Default message", which for dependabot PRs would be the very concise "Bump X from vA.B.C to vX.Y.Z" and some details in the description:

And for all other authors use "Default to pull request title and description".

Click to see (not even all of) a commit with the PR description from dependabot as the message

[luisrayas3]

I would like to request a way to specify boundaries for what to include in the commit message. The use case for our team is that our template includes a checklist of things related to the PR that don't make sense or would be too noisy to be included in the git history. In our case a comment for which everything below is excluded would be sufficient but both begin/end might make sense for completeness. Example:

<!-- github-commit-message-begin -->  <!-- This line would ideally be optional -->
This is the main description
which we do want in the commit message body.

<!-- github-commit-message-end -->
## Merge checklist
- [ ] This is too much
- [ ] We don't want it in the commit message

[igorsafo]

In case of a project that has multiple repositories with different set of branches, PRs and issues, adding a PR number into the commit title by default results in weird references to wrong PRs when the branches between repositories are synced. It would be nice to have an option to remove a PR number from the title:

• repo 1: commit "foo (#PRX)" -- points to a PR X in repo 1
• repo 2: commit "foo (#PRX)" -- points to a PR X in repo 2 that is different from the original one

[daniellowell]

Can we have an option that does not include the PR title? In our org there is typically internal information that we do not want to be carried into the commit messages. As a safety it would be good to not have PR titles into commit messages as an option for all contributors.

[tomsiewert]

What I'm currently missing is an option to add trailers such as Merged-by, Reviewed-by or Approved-by to the merge commit message.

This makes it easier to identify who reviewed or approved a PR by simply checking the git log.

[kaidokert]

Would it ever be possible to optionally disable editing the default merge message altogether ? We are trying to keep a clean standard as to what goes into the merged commit message, and that's all doable with workflow runs - we can check the PR title, description, commits and anything else we need.

However, the final action of submitting/merging happens after all of the checks have passed, and it gives everyone who merges full control to submit anything they want.

[bewuethr]

You could get there with a branch protection that lets only a bot account merge, and people trigger a merge with a comment (similar to @dependabot merge) for the bot to then merge in the way you want.

[kaidokert]

Thanks for the idea - yes this might work as a crutch. It would make the user interface less than obvious though, and would need extra thought if we allow both squash and merge and regular merge submits. Perhaps merge queue would give us a similar option, i haven't really looked yet.

[kimhanse]

Could this feature be extended to also affect the commit message prepared when using auto-merge?

[karfau]

I don't understand your question, this is all that this feature is about.

[thomaseizinger]

At the moment, the PR number is included in brackets at the end of the title. However, the standard way of linked to things in commit messages is to use trailers. It would be great if there was an option to either configure that or change the default. I'd like to see something like:

This is my commit title

Here is a body. This used to be the PR description.

Pull-Request: #1234.

[BenSluis]

It would be super helpful if the default could be controlled not just at the repository level but also in specific branch protection rules.

[max-hartman]

It would also be great to be able to have the entire URL for the PR in the last line of the commit body (could ideally be set programmatically in a template. The PR number at the top is nice, but when I'm in my terminal and I want to look a commit, I don't have a way to click into and open the PR for that commit. Some IDEs try to provide support for this by having "Issue Navigation" (allowing regex matching on snippets of the commit to create a URL from), but since its at the project level, once I have multiple repos in the same workspace it doesn't know which repo PR (# 123) belongs to.

[schoetbi]

I second @BenSluis that there also should be a relation to the rules that can be setup to ensure a certain format for commit messages. For example, we want to ensure with a rule that the commit message for a pull request merge message adheres to be in the format of a conventional commit message. We need this to be able to generate the release notes later automatically with git cliff.

So the workflow should be like this:

• The PR creator prepares the first line of the commit message in the PR title
• Details for the commit can be placed in the PR description
• If the target branch has any rules for the commit message, this should be shown as a prerequisite before the merge is allowed
• If any rule is not fulfilled, the rule name that avoids this should be shown in red.

[amartyaroy1]

hello @willsmythe
I liked this feature which is rolled out.I am curious to know is it possible to get these settings via grapql also.I tried via rest api so there is a field named as use_squash_pr_title_as_default: true/false which signifies that these settings are enabled or not. But i want to check whether these new settings are enabled or not in repos via graphql so can i get it? Can you please point which field will give me the resultant output?

I tried out these fields
mergeCommitTitle: "MERGE_MESSAGE",
squashMergeCommitMessage: "COMMIT_MESSAGES",
squashMergeCommitTitle: "COMMIT_OR_PR_TITLE",
but these are the not the ones that we want

[Martiix]

This is great! However, I would also like to be able to set a default commit message format for the revert button in the GUI:

Any chance this will happen anytime soon? :)

[nayefserag]

Is it possible to configure this via .github/settings.yml ?

[mark-wiemer]

Is this feature still supported? I can't find this setting anywhere, am I blind?

[bewuethr]

It's on the top-level settings page of any specific repository, like https://github.com/OWNER/REPO/settings, under "Pull requests":

[mark-wiemer]

Thanks! I kept looking for it as an option in the settings nav or from the branch rules section.

[zane131]

This is almost exactly what I need. However, this feature adds Signed-off-by: and Co-authored-by: trailers to the end of the message and inserts ------ in between those trailers and the trailers in the PR description.

While the autogenerated trailers are appropriate (and a nice feature add), the separation of the two sets of trailers breaks commands like git log --format="%(trailers)" because only the last block of text in the commit message is recognized as trailers and the important trailers from the PR description are effectively ignored.

Also, as stated above, the PR number added to the title only has context to the original repository and causes confusion in forks.

[Takym]

Are there any options for using a custom default commit message?

[AndiDog]

Voting against putting the PR description into the commit message. Auto-adding the description is often just unnecessary bloat. Do you want a commit message containing this? It's a real, rendered, filled-out example for a perfectly fine PR template of an open source project, but only relevant in the PR review, not in the commit message:

What type of PR is this?
/kind feature

What this PR does / why we need it: Implements the MachinePool Machines clusterAPI proposal

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes https://github.com/kubernetes-sigs/cluster-api-provider-aws/issues/4184

Special notes for your reviewer:

Checklist:

    squashed commits
    includes documentation
    adds unit tests
    adds or updates e2e tests

Release note:

Added AWSMachines to back the ec2 instances in AWSMachinePools and AWSManagedMachinePools.

The reason why I upvoted this feedback idea is because users typically just click the merge button, accepting the default commit message without editing, so the default must be minimalistic and reasonable. Only the PR title can be expected to be fine in most cases. Organizations want to avoid committing stuff like this, just because the PR author needed to make a few expected pushes to make CI green, or finish the feature:

🌱 Implement the actual thing (#12345)

* Implement the actual thing

* Address review comments

Signed-off-by: The Author author@example.com

* Address some more review comments

Signed-off-by: The Author author@example.com

* Address smoe more review comments

Signed-off-by: The Author author@example.com

* Address more review findings

---------

Signed-off-by: The Author author@example.com

Suggestion:

• Keep only PR title and number as default commit message
• Optional: take over Co-authored-by, Signed-off-by and other well-known annotations, but remove duplicates
• Make that the global default across GitHub, so organizations don't have to configure something to get rid of the above, horrible squash commit messages that happen because users (rightfully) accept the default and hit the merge button.
• Allow PR author to choose from other presets before clicking the merge button, such as PR title+description and whatever other choices get implemented. This offers the people who care about commit messages – those who don't click the merge button immediately – to more easily apply the desired template if the default doesn't suit them.

[spydon]

There is a beta feature rolled out to some repositories where you can remove parts of the PR description, see here for example:
https://raw.githubusercontent.com/flame-engine/flame/refs/heads/main/.github/pull_request_template.md
Then you will only get what the user has written.

What would be even better is if there was a form on the PR page, like the new forms for issues, so that the user doesn't have to manually edit markdown when submitting a PR.

[zane131]

Voting against putting the PR description into the commit message. Auto-adding the description is often just unnecessary bloat.

It really depends on the use case. My organization utilizes elements on the commit message, particularly in the trailers, for tracking purposes. This isn't for everyone, but is incredibly helpful for us.

Also, my organization has a set of maintainers that will do the "Squash and merge", which very likely will not be the author of the pull request. By utilizing the description we know what the author intended to have as the commit message of the squashed pull request. This takes the burden off of the maintainers so that they do not need to generated a formatted commit message. Instead, they can, as you say, "just click the merge button."

Again, it all depends on the use case. That is why it is nice to have the option.

[bartgol]

I would still very much like to customize the message via some yml file in the .github folder. E.g., I would like to be able to add info such as the labels that were attached, or the assignees/reviewers list, or the name of who effectively merges the PR. E.g., a merge-commit-default.yaml file like the following (some may not be possible, but for just the sake of showing the idea)

headline: Merge pull request {pr.number} from branch {pr.head.ref}

body: |
  PR Title: {pr.title}
  PR Author: {pr.author}
  PR Labels: {pr.labels}
  PR Reviewers: {pr.reviewers}
  PR Approved by: {pr.reviewers_approved}
  PR Assignees: {pr.assignees}
  
  Merged by: {user}

This way, I can quickly parse my git history for merging of PRs that had certain labels, or that were reviewed by user X, or merged by user Y.

[Takym]

I suggest the below placeholders and flag to avoid https://github.com/orgs/community/discussions/142044.

• {pr.number.safe} placeholder - a number with the fork owner and repository name.
  • Format: <FORK_OWNER_NAME>/<FORK_REPO_NAME>#<NUMBER>
• {pr.number.unsafe} placeholder - a number only. Same with {pr.number}. This is for the private repositories.
  • Format: #<NUMBER>
• A flag to determine converting commit messages from unsafe issue/pull request numbers to safe. I propose names are as follows:
  • use_safe_numbers
  • convert_numbers
  • use_safe_issue_pr_numbers
  • convert_issue_pr_numbers
  • issue_pr_number_format with enum values: no_converted, safe, unsafe, optimized
    • (optimized means safe for other repositories, unsafe for the current repository)
  • number_format - issue_pr_ is redundant?

Edit: I dropped use_safe_numbers, convert_numbers, use_safe_issue_pr_numbers, and convert_issue_pr_numbers and added number_format.