From c23a5e7e8c044717c7dd61599edf516b5dc8cd50 Mon Sep 17 00:00:00 2001
From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com>
Date: Thu, 12 Mar 2026 01:42:45 -0700
Subject: [PATCH] Document custom merge commit titles via PR body directive

Add docs for the `merge-commit-title:` directive that lets users specify
a custom merge commit title by adding it on its own line in the PR body.
Updates the submit/cancel page, FAQ, and advanced settings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../administration/advanced-settings.md       | 10 ++++++++
 merge-queue/reference/common-problems.md      |  2 ++
 merge-queue/using-the-queue/reference.md      | 25 +++++++++++++++++++
 3 files changed, 37 insertions(+)

diff --git a/merge-queue/administration/advanced-settings.md b/merge-queue/administration/advanced-settings.md
index f7e0c2dc..edbb0563 100644
--- a/merge-queue/administration/advanced-settings.md
+++ b/merge-queue/administration/advanced-settings.md
@@ -173,7 +173,17 @@ You can change your merge method at any time:
 
 The merge method is configured per repository, so different repositories in your organization can use different methods based on their needs.
 
+### Custom merge commit titles
 
+You can override the merge commit title on a per-PR basis by adding a `merge-commit-title:` directive on its own line anywhere in the PR body:
+
+```
+merge-commit-title: feat(auth): add OAuth2 login flow [PROJ-123]
+```
+
+When present, Trunk uses this title for the merge commit instead of the default GitHub-generated title. The commit body follows the usual behavior for the configured merge method. When the directive is not present, the default behavior is preserved.
+
+See [Submit and cancel pull requests](../using-the-queue/reference.md#custom-merge-commit-titles) for more details and examples.
 
 ***
 
diff --git a/merge-queue/reference/common-problems.md b/merge-queue/reference/common-problems.md
index 662e1612..27ff2f90 100644
--- a/merge-queue/reference/common-problems.md
+++ b/merge-queue/reference/common-problems.md
@@ -62,6 +62,8 @@ Commit messages depend on your configured merge method:
 * **Merge Commit**: Preserves all individual commit messages from the PR and creates an additional merge commit message
 * **Rebase**: Preserves all individual commit messages from the PR as they are replayed onto the target branch
 
+You can override the merge commit title for any PR by adding `merge-commit-title: Your Custom Title` on its own line in the PR body. See [Custom merge commit titles](../administration/advanced-settings.md#custom-merge-commit-titles) for details.
+
 You can configure your preferred merge method in [Advanced Settings](../administration/advanced-settings.md#merge-method).
 
 </details>
diff --git a/merge-queue/using-the-queue/reference.md b/merge-queue/using-the-queue/reference.md
index e9544698..68a98caf 100644
--- a/merge-queue/using-the-queue/reference.md
+++ b/merge-queue/using-the-queue/reference.md
@@ -34,6 +34,31 @@ trunk login
 trunk merge cancel <pr-number>
 ```
 
+## Custom merge commit titles
+
+You can specify a custom merge commit title for any PR by adding a `merge-commit-title:` directive on its own line anywhere in the PR body:
+
+```
+merge-commit-title: Your Custom Commit Title Here
+```
+
+When Trunk merges the PR, it uses this title instead of the default GitHub-generated title. When the directive is not present, the default behavior is preserved.
+
+This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want cleaner git history.
+
+### Example
+
+```markdown
+## Description
+This PR adds user authentication.
+
+merge-commit-title: feat(auth): add OAuth2 login flow [PROJ-123]
+```
+
+{% hint style="info" %}
+The `merge-commit-title:` directive only customizes the commit **title**. The commit body follows the usual behavior for your configured [merge method](../administration/advanced-settings.md#merge-method).
+{% endhint %}
+
 ## Pull request processing
 
 Once a PR is submitted to the merge queue it goes through several states. First, it starts as _Queued_ until all of the required conditions to submit it are met. Once ready, the PR moves to the _Pending_ state, waiting for a Merge Queue to pick it up, and then enters the _Testing_ state. Once the tests pass the PR may still need to wait for upstream PRs. Once any upstream PRs are complete the PR will be merged and then removed from the Merge Queue. If a PR fails or is canceled then it will go to the failed or canceled state.