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

[brasic]

I think perhaps rather than an option it makes more sense to always omit HTML comments. Can you suggest a scenario where these would be wanted in the commit message?

[tiit-clarifai]

Not really, I am fine with always omitting.

[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.

[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.

[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 ?