Setup

How to set up Trunk Merge for your project

Connect your Trunk Organization to GitHub

Sign up at app.trunk.io, 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:

Automatic (default)

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.

Custom (trunk.yaml)

version: 0.1 

cli:
  version: 1.16.0
merge: 
  required_statuses:
    - Trunk Check 
    - Unit tests & test coverage
    # Add more required statuses here

Use custom when the status checks you want to enforce before merging do not match 1:1 with your GitHub branch protection rules. The names of the required_statuses must match as specified on your GitHub status checks or jobs Custom required_statuses defined in the .trunk/trunk.yaml file take precedence over the GitHub required status checks from branch protection.

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
on:
  push:
    branches:
      - trunk-merge/**

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

  unit_tests:
    runs-on: ubuntu-latest
    # "Unit tests & test coverage" is specified in merge.required_status above
    name: Unit tests & test coverage
    steps:
      - 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.

GitHub Pull Request View

Comment /trunk merge on a pull request

Trunk CLI

# Authenticate with trunk service
$ trunk login
# Queue pull request for merge
$ trunk merge {pr-number}

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.

Success!

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.