Skip to content

[TRUNK-17691] Document custom merge commit titles via PR body directive #456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
samgutentag wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[TRUNK-17691] Document custom merge commit titles via PR body directive #456

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions merge-queue/administration/advanced-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

***

Expand Down
2 changes: 2 additions & 0 deletions merge-queue/reference/common-problems.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@claude claude bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cross-reference here links to advanced-settings.md#custom-merge-commit-titles, but that section is a brief summary which itself redirects the reader back to reference.md for "more details and examples." This creates an unnecessary two-hop navigation path for users.

Since the comprehensive documentation (syntax, full example, usage guidance) lives in reference.md, consider linking there directly:

Suggested change
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 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](../using-the-queue/reference.md#custom-merge-commit-titles) for details.


You can configure your preferred merge method in [Advanced Settings](../administration/advanced-settings.md#merge-method).

</details>
Expand Down
25 changes: 25 additions & 0 deletions merge-queue/using-the-queue/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Copy link
Contributor

@claude claude bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Potential accuracy issue (open question #1 from PR): This sentence doesn't restrict which merge methods the directive applies to, but the PR itself asks: "Does merge-commit-title: work with rebase merge method, or only squash and merge commit?"

If the directive only works with Squash and Merge Commit methods (not Rebase), the docs here will be misleading for users on a Rebase workflow. Before merging, please verify this and either:

  • Confirm it works with all three methods (no change needed), or
  • Add a note scoping it, e.g.: "This directive applies to Squash and Merge Commit methods. It has no effect when using the Rebase merge method."


```
Copy link
Contributor

@claude claude bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open questions #2 & #3 from PR (case sensitivity & length limits): The docs don't mention whether the directive is case-sensitive or if there are character/length limits on the title value. If these are relevant constraints, they should be documented here or in the hint block. For example:

Note: The directive is case-sensitive — Merge-Commit-Title: will not be recognized. Titles have a maximum length of X characters.

Resolve these before merging to avoid a follow-up correction.

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.
Copy link
Contributor

@claude claude bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor grammar nit: "cleaner git history" should be "a cleaner git history."

Suggested change
This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want cleaner git history.
This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want a 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" %}
Copy link
Contributor

@claude claude bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hint says the directive "only customizes the commit title" but it would be clearer to echo the directive name and say "merge commit title" — matching the phrasing used in the heading and throughout the section:

Suggested change
{% hint style="info" %}
The `merge-commit-title:` directive only customizes the merge commit **title**. The commit body follows the usual behavior for your configured [merge method](../administration/advanced-settings.md#merge-method).

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.
Expand Down
Loading