Submit and cancel pull requests

Covers the journey of a PR from submission through various states to completion

Submitting and cancelling pull requests

We offer a few mechanisms for submitting a PR to the Merge Graph:

• Posting a GitHub comment /trunk merge on a pull request.
• Ticking the checkbox in the Trunk comment on a pull request.
• Clicking the “Retry” button on the WebApp.
• Using the trunk CLI:

trunk login
trunk merge <pr-number>

Admins can also use /trunk merge --force to push a PR through the queue when branch protection isn’t satisfied.

We offer similar commands for cancellation.

• Posting a GitHub comment /trunk cancel on a pull request.
• Cancellation from the WebApp:

• Using the trunk CLI:

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.

The directive name is case-sensitive. It must be lowercase merge-commit-title:. Variations such as Merge-Commit-Title: are not recognized.

This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want a cleaner git history.

Example

## Description
This PR adds user authentication.

merge-commit-title: feat(auth): add OAuth2 login flow [PROJ-123]

The merge-commit-title: directive only customizes the merge commit title. The commit body follows the usual behavior for your configured merge method.

The directive applies to the Squash and Merge Commit merge methods. It has no effect when using Rebase, since rebase replays the original commits onto the target branch and does not produce a separate merge commit.

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.

Pull request states

A PR’s lifecycle in the Merge Queue goes through the following states:

State	Description
Queued	The PR was submitted to Trunk Merge Queue, but the PR isn’t eligible for merging yet. Impacted targets may not be uploaded, or readiness checks may not have passed.
Pending	The MergeGraph created a node for the PR. Testing will begin if the graph has capacity.
Testing	The PR is testing. Required status checks that Trunk Merge Queue must gate on before merging PRs can be specified with in .trunk/trunk.yaml or through GitHub branch protection rules as the “Status checks that are required” before merging on your merge branch
Tests Passed	The PR successfully passed tests. It may have to wait for upstream PRs to complete tests before merging.
Pending Failure	The PR failed tests. The cause of failures is still indeterminate - it may be due to an upstream PR, or due to the current PR. It will wait until the root cause of tests has been determined, and restart testing on your PR if due to an upstream PR. If you want to manually restart a failed PR, see manually restarting PRs.
Merged	The PR successfully merged into the target branch. It will be removed from the queue.
Failed	The PR caused a testing failure. It will be removed from the queue.
Cancelled	The PR was cancelled, e.g. /trunk cancel. It will be removed from the queue.