How to set up Trunk Merge for your project

Connect your Trunk Organization to GitHub

Sign up at, create a Trunk organization, and connect it to your GitHub repositories. If your repository is already connected to your Trunk organization, you can skip this step.

Select the repository you would like to use and click Get Started.

Set Up Trunk Merge

Go to the Merge tab. You will see the "Set Up Trunk Merge" page. From there, you can specify:

  1. The name of the branch that Trunk Merge should help manage merging PRs into.

  2. The number of Pull Requests that Merge can test at the same time.

  3. The mode that Trunk Merge Queues will start in.

Define Required Status Checks For Testing

Trunk needs to know which status checks must pass while testing pull requests in the queue before it can merge a PR into your branch. Merge can pick up this list of required statuses in one of two ways:

In automatic mode, the status checks specified in your branch's GitHub branch protection rule will be used. See GitHub's doc for more information on configuring required status checks.

Configure a Push Triggered Workflow For Required Status Checks

Trunk Merge creates branches with the prefix trunk-merge/ in order to test PRs. To ensure the required statuses Merge should gate on get triggered when it tests PRs, your CI provider must be configured to run the status checks you care about whenever a branch with that prefix is pushed to.

For GitHub Actions, that'll mean setting up a push-triggered workflow, filtered to trunk-merge/** branches, like so:

name: Run Required Checks
run-name: PR Checks for ${{ github.ref_name }}

# Trigger jobs whenever Trunk Merge tests a PR using a `trunk-merge/` branch
      - trunk-merge/**

    runs-on: ubuntu-latest
    # "Trunk Check" is specified in merge.required_status above
    name: Trunk Check
      - name: Checkout
        uses: actions/checkout@v3

    runs-on: ubuntu-latest
    # "Unit tests & test coverage" is specified in merge.required_status above
    name: Unit tests & test coverage
      - name: Checkout
        uses: actions/checkout@v3

    # Add more steps here..    

Now you are ready to submit your first PR. Let's go!

Submit Pull Requests

Try making a simple change on a branch and submit it as PR in GitHub.

Now trigger Trunk Merge to process this PR using either a comment on the PR in GitHub or using the Trunk CLI.

Comment /trunk merge on a pull request

If you have any problems with merge queueing PRs, take a look at the branch protection docs.

Pull Request Processing

Once a PR is submitted to the Merge queue, it will start as Not Ready until all of the required conditions to submit it are met. Once ready, the Merge Queue will pick it up and run the tests. Once the tests pass, the PR may still need to wait for upstream PRs in the queue to finish their testing. Once the remaining 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. Read more about PR States.


Now Trunk Merge is setup with your repo. Whenever a PR is pushed to your merge branch it will be safely tested and automatically merged when all tests pass, regardless of the order they were pushed in.

Next Steps

You can configure parallel mode for potential performance gains, read how to cancel pull requests, and setup a Slack Integration. If you are using Bazel you may want to further customize it for parallel mode.

Last updated