trunk-action

trunk-action copied to clipboard

Trunk GitHub Action

This action runs trunk check, a super powerful meta linter and formatter, showing inline annotations on your PRs for any issues found. Trunk runs just as well locally as on CI, so you can always quickly see lint issues before pushing your changes.

Get Started

Before setting up running Trunk Check on CI, you'll need to initialize trunk in your repo. Initializing it (trunk init) bootstraps a the trunk configuration (.trunk/trunk.yaml) which stores all the configuration for Trunk. All linters and formatters, as well as the version of Trunk itself, are versioned in trunk.yaml, so you're guarnateed to get the same results whether you're running locally or on CI.

Check out the Trunk CLI and VS Code extension to start using Trunk locally.

1. Install Trunk → curl https://get.trunk.io -fsSL | bash
2. Setup Trunk in your repo → trunk init
3. Locally check your changes for issues → trunk check
4. Locally format your changes → trunk fmt
5. Make sure no lint and format issues leak onto main → You're in the right place 👍

Usage

steps:
  - name: Checkout
    uses: actions/checkout@v3

  # >>> Install your own deps here (npm install, etc) <<<

  - name: Trunk Check
    uses: trunk-io/trunk-action@v1

(See this repo's pr.yaml workflow for further reference)

Installing your own dependencies

You do need to install your own dependencies (npm install, etc) as a step in your workflow before the trunk-io/trunk-action step. Many linters will follow imports/includes in your code to find errors in your usage and thus they need you to have your dependencies installed and available.

If you've setup basic testing on CI, you're already doing this for other CI jobs; Do it here too 😉. Here's some GitHub docs to get you going: [nodejs, ruby, python, many more]

Caching

Caching is on by default: Trunk will cache linters/formatters via actions/cache@v2. This is great if you are using GitHub-hosted ephemeral runners.

If you are using long-lived self-hosted runners you should disable caching by passing cache: false as so:

- name: Trunk Check
  uses: trunk-io/trunk-action@v1
  with:
    cache: false

Note: Previous versions of the Trunk GitHub Action did not include caching. If you were previously using actions/cache@v2 to cache Trunk, please remove it from your workflow.

Linters

We integrate new linters every release. If you have suggestions for us, please request it here or stop by in our Slack - we always love hearing from our users!

We currently support the following linters.

Of the aforementioned linters, these are the ones we consider to be "formatters", which means that if you modify the file, you must re-format it appropriately.

Trunk versioning

After you trunk init, .trunk/trunk.yaml will contain a pinned version of Trunk to use for your repo. When you run trunk, it will automatically detect which version you should be running for a particular repo and download+run it. This means that everyone working in a repo, and CI, all get the same results and the same experience. no more "doesn't happen on my machine". When you want to upgrade to a newer verison, just run trunk upgrade and commit the updated trunk.yaml.

Run Trunk outside of GitHub Actions

Trunk has a dead simple install, is totally self-contained, doesn't require docker, and runs on macOS and all common flavors of Linux.

1. Install Trunk → curl https://get.trunk.io -fsSL | bash
2. Setup Trunk in your repo → trunk init
3. Check your changes for issues → trunk check
4. Format your changes → trunk fmt
5. Upgrade the pinned trunk version in your repo → trunk upgrade

Check out our docs for more info.

Running trunk check on all files

By default trunk check will run on only changed files. When triggered by a pull request this will be all files changed in the PR. When triggered by a push this will be all files changed in that push. If you would like to run trunk check on all files in a repo, you can set the check-mode to all. For example:

- name: Trunk Check
  uses: trunk-io/trunk-action@v1
  with:
    check-mode: all

If you're running an hourly or nightly job on a branch, check-mode is automatically inferred to be all.

Uploading results to the Trunk web app

The Trunk web app can track results over time, give upgrade notifications and suggestions, and more. For security, we never clone your repo in our backend. Instead, you set up a periodic CI job to run trunk check on your repo and it sends the results to Trunk.

By providing a trunk-token (as seen below) and running on a schedule workflow dispatch (example), Trunk will infer to run with check-mode as all and to upload results to Trunk.

- name: Trunk Check
  uses: trunk-io/trunk-action@v1
  with:
    trunk-token: ${{ secrets.TRUNK_TOKEN }}

Note: When run as a periodic workflow on a branch, Trunk will automatically infer check-mode to be all.

(See this repo's nightly.yaml workflow for further reference)

Running trunk check on multiple platforms

If you'd like to run multiple Trunk Check jobs on different platforms at the same time, you can pass label to each job to distinguish them. For example:

- name: Trunk Check
  uses: trunk-io/trunk-action@v1
  with:
    arguments: --github-label=${{ runner.os }}

Annotating existing issues

By default the Trunk Action will only annotate new issues, but if you also want to annotate existing issues you can pass --github-annotate-new-only=false to Trunk Check. For example:

- name: Trunk Check
  uses: trunk-io/trunk-action@v1
  with:
    arguments: --github-annotate-new-only=false

Usage with the github merge queue

Trunk auto-detects when it is running from the github merge queue and will check only the files being merged. The "Merge commit" and "Squash and merge" strategies are currently supported. "Rebase and merge" does not yet work correctly.

Feedback

Join the Trunk Community Slack. ❤️