Merge commit message template

[akwodkiewicz]

I would like to enforce particular message style for the merge commits. It would be very handy to have some .github/MERGE_COMMIT_TEMPLATE config file that would be parsed by Github and pre-filled the commit message accordingly when somebody clicks on "Merge pull request" button.

In particular, I would like to achieve something like this:

merge(${PR_ID}): ${PR_TITLE}

${PR_DESCRIPTION}

instead of the regular:

Merge pull request #1234 from organization/branch/name 

[quezak]

Great idea! One caveat to think about: ${PR_DESCRIPTION} might be large

[alexykot]

This can be easily solved by adding a ${PR_DESCRIPTION_TRIM} option that is trimmed to a certain reasonable length. Also cool would be to have a ${PR_URL} var, to enable easy click-through to the original PR to view full description.

[akwodkiewicz]

optionally, the template could include variables like "creator", "reviewers" or "labels"

[macbem]

This would work great for automated changelog management plus it'd be a killer feature for companies using convenvional commits. Pretty please 🙏🏽

[alexykot]

This would be a great addition for us as well. We use rebase-squash-merge flow, and merge commit message in master are the only artefacts that stay with us long term, while feature branches get trimmed quickly. Because they get trimmed quickly - we don't really care about commit messages as much, and pay attention to PR descriptions instead to inform reviewers about the context of particular changeset.

This means that a bullet-list of commit messages that is by default used as merge commit message is largely useless for us, while PR description is not added to git history, and the only way to see it is to manually pick out the PR number and search for it, which is far from ideal.

This proposal would preserve current default behaviour, but would also allow us to customise it to better fit our workflow.

[umutoztunc]

We would love to see this feature implemented. We are using a gerrit-like workflow where each PR is squashed into 1 commit. However, we also would like to add some extra information like PR id, reviewer list, related issues etc. in the commit message just like Gerrit does.

This feature would be beneficial to everyone since it is hard to please everyone by offering some workflows to choose from. It is nice to offer some things, but some people would still prefer customizing their own workflow.

We have noticed that GitLab has this feature. A similar template system would be great!

[ollytheninja]

Using Conventional Changelog and would like to enforce commit message syntax to align with that :)

[825i]

Is this still not currently possible? I am aware that we can set a commit template, but changing eg. this:

Does not seem possible at all, at least not with Github actions (which is what I am trying to do). Does anyone have any ideas?

[dedesvik]

We make a lot of automatic merge requests which need to be approved manually so having a template for these merge request comments that can be checked and filled in by a human would be highly useful.

[dedesvik]

This is definitely not a solution via Github means but seeing as our MRs come from Jenkins, we decided to set the template on Jenkins side with the following plugin: https://articles.assembla.com/en/articles/748190-configure-jenkins-ci-integration-with-merge-requests

It takes arguments such as:

$mrTitle - merge request title
$mrAbbrTitle - merge request title truncated to 30 chars
$mrUrl - merge request url
$mrId - merge request id

At least in this way we can have this passed to Github.

[jasonkuhrt]

Need this to enforce good conventions in our team for automating good changelogs.

A template is nice but I'd like to see something further that also prevents malformed commit bodies according to some specific pattern.

Thus I would like the template to specify not just content and content slots but also a way to encode what patterns will be accepted or not.

At the most basic I think a regex could do the job in some cases, though writing complex regexes that cover patterns spanning multiple lines easily gets complex fast. Still, I'd be so happy for it to be possible at this point, not caring so much about easy–so long as can make the day to day easy with some one-time hard regex authorship :)

[Jolg42]

Alternatively, maybe try https://github.com/changesets/changesets?

[jasonkuhrt]

How does that enforce anything in the GitHub UI though?

[Jolg42]

Doesn't help with GitHub UI but with good changelogs :)

[jameslnewell]

I'd like this too so we can include the PR's branch name (which contains the ticket name) in the message

[gabrielfeo]

Having the PR description go into commit messages is extremely valuable for searchability and portability. I can't grep the log from GitHub and I enjoy being able to read the most complete log I can from wherever my repository is: be it GitHub, local git or GitLab. I use a strictly merge commits workflow on some projects, strictly squash commit on others. I think this would be important for both merge strategies.

What some of us do to work without this feature today:

• manually copy-paste PR description in the merge box before merging: easy to forget, cumbersome on any project and unreliable when there's many collaborators
• implement a custom merging automation and block merges through GitHub UI*: for most projects this isn't worth doing, I believe, so they live with the problem or the previous solution

I think we should stick to the basics first, a simple template system just like GitLab. Validations like @jasonkuhrt mentioned would also be nice (GitLab has this too), although I'd be happy with simple templating.

*like commenting "merge" on a PR, listening somewhere and doing the merge with the message you want to enforce

[ollytheninja]

easy to forget, cumbersome on any project and unreliable when there's many collaborators

Exactly!

Re: blocking merging through the UI and having users comment, I've just implemented this for a GitOps style workflow that needs a fast forward merge. It's achievable (GitHub actions can be triggered on PR comment) but it's a far worse User Experience and a pain to setup and configure than simply having a template!

[xsurfer]

Does this help?
https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests

[ollytheninja]

Hi Fabio, thanks for the link! A few thumbs down on your comment but no one stopped to comment.
While the linked functionality is really useful for controlling how contributors merge, it doesn't help with guiding or controlling the content of the final commit message in a merge commit.

[xsurfer]

Actually I was referring to the Default to PR title for squash merge commits functionality and personally, it helped!

I added a step in my CI pipeline which consumes GitHub API to validate the PR title (I want to enforce given naming convention, e.g. reference to external user story). Then, with the setting on, the commit message for the PR got defaulted to the PR title 😉
Of course, in my case I wanted to enforce squash merging.

[akwodkiewicz]

Thank you @xsurfer, it's really helpful. I did not know about this feature. However:

• this option is available only for squash merge commits
• it only lets you populate the commit title with the PR title -- no configuration here, no option to populate description

so it definitely might help some people, but it's not a solution to my original proposal.

[Frederick888]

Not really a solution, but I want to

• commit merge commits using my own email
• sign merge commits using my PGP key
• always have into <target base> like git config merge.suppressDest ""

So taking advantage of gh-cli, I added this alias to my .gitconfig:

mpr = !"                                                                                                                                                \
	function merge_github_pr() {                                                                                                                        \
		set -e;                                                                                                                                         \
		local RED='\\033[0;31m';                                                                                                                        \
		local NC='\\033[0m';                                                                                                                            \
		if [[ \"$(ps -o comm= $PPID)\" =~ ^n?vim$ ]] || [[ \"$(tput colors)\" != \"256\" ]]; then                                                       \
			RED='~'; NC='~';                                                                                                                            \
		fi;                                                                                                                                             \
		local pr_stats;                                                                                                                                 \
		pr_stats=\"$(gh pr status --json number,baseRefName,headRefName,headRepositoryOwner --jq .currentBranch)\";                                     \
		if [[ -z \"$pr_stats\" ]]; then                                                                                                                 \
			printf 'Failed to find PR for current branch!\n';                                                                                           \
			exit 1;                                                                                                                                     \
		fi;                                                                                                                                             \
		local pr_number;                                                                                                                                \
		local pr_base_ref;                                                                                                                              \
		local pr_head_ref;                                                                                                                              \
		local pr_head_owner;                                                                                                                            \
		local pr_merge_subject;                                                                                                                         \
		pr_number=\"$(jq -r .number <<<\"$pr_stats\")\";                                                                                                \
		pr_base_ref=\"$(jq -r .baseRefName <<<\"$pr_stats\")\";                                                                                         \
		pr_head_ref=\"$(jq -r .headRefName <<<\"$pr_stats\")\";                                                                                         \
		pr_head_owner=\"$(jq -r .headRepositoryOwner.login <<<\"$pr_stats\")\";                                                                         \
		pr_merge_subject=\"$(printf 'Merge pull request #%d from %s/%s into %s' \"$pr_number\" \"$pr_head_owner\" \"$pr_head_ref\" \"$pr_base_ref\")\"; \
		printf 'Gonna merge current branch with subject %b%s%b, sure? [y/n] ' \"$RED\" \"$pr_merge_subject\" \"$NC\";                                   \
		read -n 1 -r; printf '\\n';                                                                                                                     \
		if [[ \"$REPLY\" != 'y' ]]; then                                                                                                                \
			exit 0;                                                                                                                                     \
		fi;                                                                                                                                             \
		git checkout \"$pr_base_ref\";                                                                                                                  \
		git merge --no-ff --log -m \"$pr_merge_subject\" \"$pr_head_ref\";                                                                              \
	};                                                                                                                                                  \
	merge_github_pr                                                                                                                                     \
"

(I know this looks horrible. Don't judge me lol)

[mlippert]

Adding my 2 cents and copying my post in the squash and merge thread in the community forum to here.
Since the MERGE_COMMIT_TEMPLATE is already an option for squash merges, all I'm asking is to expand it to also work for regular merge commits as well.

Like @dp185133 I also want to be able to configure my PR merge commit message for regular merge commits.
As a specific example I’d like to define my default MERGE_COMMIT_MESSAGE to be:

feat: PR #{id}: {title}

Issues:
Merge: {sourceBranch} => {targetBranch}
Approved-by: {approvedByList}

[403-html]

casually bumping thread

that'd be awesome addition to github's templates

#{PR ID): {PR title}

would be so great

[nderjung]

In the Unikraft OSS Project we make use of a convention which is not yet possible using GitHub's PR merge system. The result is that merged PRs are marked as "closed" instead of "merged" and we use a custom label ci/merged to mark the differentiation.

Similar to the approach made by the Linux kernel, merging a PR in our project involves an exhaustive review proccess which includes both a "reviewer" and an "approver". These two roles, mapped to GitHub's "reviewer" and "assignee" roles, respectively, guide the PR into a mergable state. The role of the reviewer is to comb through the PR and ensure it works, is an elegant solution, and check it is meets our standards before a merge. The role of the approver (who is a project maintaiinerr) is to double check this and "LGTM" the review and the PR. We ensure that every commit makes sense and leaves the repository in a working state through a single linear history -- it is not simply a case of providing new functionality as it is also about idempotency. Since one of the pilar's of Unikraft as a kernel is security, our philosophy is that every commit and its change reflects a well-defined intention to ensure integrity.

As a result and to accommodate for the fact that there can be many people involved in the merging of a PR, we include their name in each commit of the PR. Here is an example commit message:

lib/posix-event: Add eventfd system call
This commit adds implementations for the eventfd class of system calls
based on the eventpoll API.

Signed-off-by: Marc Rittinghaus <marc.rittinghaus@kit.edu>
Reviewed-by: Cezar Craciunoiu <cezar.craciunoiu@gmail.com>       ┐
Reviewed-by: Razvan Deaconescu <razvan.deaconescu@cs.pub.ro>     │
Approved-by: Razvan Deaconescu <razvan.deaconescu@cs.pub.ro>     ├──► added systematically by our merge program
Tested-by: Unikraft CI <monkey@unikraft.io>                      │
GitHub-Closes: https://github.com/unikraft/unikraft/pull/485     ┘

This means we have had to build a custom mechanism for adopting this philosophy. We use Concourse to achieve this (amongst other benefits it offers as a CI system). The trigger for us is that once the GitHub "assignee" (who has the permission) leaves an Approved-by: Name <EMAIL> comment (in this exact syntax), we trigger a merge. Here is an example of such a comment (note that they are the assignee of the PR).

There are a number of caveats to the current system, and I speak through the lens of GitHub's API:

• The email of the user, in whatever capacity, cannot be retrieved by the GitHub API and therefore we must ask them to leave a comment in the Git Trailer format;
• Even if possible to access a user's email (understandably non-accessible due to data-privacy / spam protection reasons), a user may have multiple emails assigned to their GitHub profile, and may be performing the review or approval under the capacity of one affiliation. E.g., it is their personal GitHub account but for their work and main business, they must "sign off" with their work email.
• For us, every commit counts and we have a standard template which is applied to each commit. Since the commit message (its synax, wording, title, description, existing trailers) is important, we do not want to modify it other than append to it. It is a built in function of Git to be able to add new trailers using git interpret-trailers.

One solution is to look at this process even more abstract, and offer the ability to mark the PR as merged as opposed to closed if we can program systematic merging. For example, we use the "special" GitHub Git Trailer to close the commit: GitHub-Closes: #.... Perhaps there could be done as a new Git trailer Merges: #...? Perhaps this marking can done as an API call? Perhaps the proposed "template" seen in previous comments could be offered in a way that applies to both the merge commit (if that is the project preference) or to a rebase (and therefore all commits)?

[HananBar]

So looks like we can now hack it together using 2 features -
Pull request templates and this (take PR commit message from PR title and description):

meaning the commit message will be taken from the pull request itself which already supports templates

[mlippert]

I don't think this helps at all except for a very specific case. I for one want my Merge commit message to be formatted and contain very different information from the PR title and description.

[clipsmm]

This would be a very nice feature PR_ID: PR_TITLE