Manual Setup
If you use GitHub, we recommend you follow the GitHub Integration guide.
If you're using GitHub but wish to setup up your own GitHub Actions Workflows, you can use the provided Trunk GitHub Action.
Caching and Persistence
Trunk caches the version of
trunk
itself, linters, formatters, and lint results, in~/.cache/trunk
If your build machines are persistent, make sure this directory is not wiped out between CI jobs for best performance. If Trunk has to re-download every linter for every job because this directory is wiped out, it will be very slow.
If your build machines are ephemeral, there are a few options for caching:
CI systems have support for caching between CI jobs on ephemeral runners:
You can include a seeded trunk cache in a regularly updated image used for CI by running
trunk check download
, which will download all requirements to~/.cache/trunk
Running trunk check
on Hourly/Nightly Builds
trunk check
on Hourly/Nightly BuildsIf you'd like to setup trunk check
to run on a hourly/nightly CI run or release branch we recommend running with the following command:
--ci-progress
will print out the tool's progress every 30 seconds, whereas --no-progress
will suppress any progress reporting.
You can also explicitly set the upstream branch if needed via --upstream
, but we do detect your main branch by default.
Uploading Results From Hourly/Nightly Builds
Trunk Code Quality has the ability to post its results to app.trunk.io. This will enable you to view your repository's Code Quality history over time so you can track the trend of issues in your code, as well as browse the issues in your repository to help you understand which issues should be prioritized to fix.
In order to keep the data up-to-date, you should upload Trunk Code Quality results regularly in an automated fashion. Depending on the size of your repository and the linters you have configured to run, running Trunk Code Quality on your whole repository may take a while. Because this run may take a while, we recommend uploading Trunk Code Quality results once daily. However, the system supports uploading results for every commit, so the granularity of upload is up to you.
Running trunk check --upload
Before running trunk check --upload
you must have connected your Github repository to your Trunk account.
CI Setup for nightly uploads
You can use the Trunk GitHub Action to upload results nightly for your main branch. You can provide it with a trunk-token
by navigating to Settings → Repositories → {your repository} and clicking "View Api Token".
Example nightly workflow to upload results: nightly.yaml
Running trunk check --upload
locally
trunk check --upload
is different than a normaltrunk check
invocation because we explicitly want the Trunk CLI to find all of the issues in the repository. Because of this, we recommend adding the--all
flag to yourtrunk check --upload
invocation. Keep in mind, this won't override the ignore settings in yourtrunk.yaml
file. Any linter or file-level ignores you have configured will be honored bytrunk check --upload
.trunk check --upload
accepts the same flags and filters astrunk check
that you run locally and for CI, and it also has the same runtime dependencies.You should run your
trunk check --upload
command locally without the--upload
flag to verify that it is working as expected. If you have a large repository or many checks enabled,--all
may take a long time. In this case, remember to use--sample
.Required command line parameters
--token
: The Trunk API token for this repository. You can find this by navigating to Settings → Repositories → {your repository} and clicking "View Api Token".--series
: This is the name of the time-series this upload run is a part of. We recommend using the name of the branch you are runningtrunk check
on. For example, we runtrunk check --upload
regularly on ourmain
branch, so we use--series main
. You may instead prefer to track specific releases or tags, or create an experimental series. The series name does not need to match any git object, it is available as a way to organize your upload data. If you're unsure of what to use for--series
, just use the name of your main branch (typicallymain
ormaster
)
Troubleshooting
Normally we infer repo information from the origin
remote, however if you don't have an origin
or for another git configuration reason it can't be inferred, it can be explicitly defined in trunk.yaml
:
Add a
repo
section to your Trunk config. This allows the Trunk CLI to connect with the appropriate repository in the Trunk system.host
: Where your repository is hosted. Currently only Github is supported, so this value should begithub.com
,owner
: The Github Owner of the repository, typically the first path section of your repository URL. For example, if we were connecting with https://github.com/google/googletest, theowner
would begoogle
.name
: The name of the repository. Continuing with our example above, thename
would begoogletest
.
This is what the repo
section of your config would look like if your repository was hosted at https://github.com/google/googletest
Note the repo/repo nested structure.
Last updated