LogoLogo
SlackLogin
  • Overview
    • Welcome
  • Setup & Configuration
    • Connecting to Trunk
    • Managing Your Organization
      • GitHub App Permissions
  • Integration with Slack
  • Flaky Tests (Beta)
    • Overview
    • Get Started
      • Test Frameworks
        • Android
        • Bazel
        • Behave
        • cargo-nextest
        • Cypress
        • Dart Test
        • Go
        • GoogleTest
        • Gradle
        • Jasmine
        • Jest
        • Karma
        • Maven
        • minitest
        • Mocha
        • Nightwatch
        • NUnit
        • Pest
        • PHPUnit
        • Playwright
        • Pytest
        • Robot Framework
        • RSpec
        • Swift Testing
        • Vitest
        • XCTest
        • Other Test Frameworks
      • CI Providers
        • Azure DevOps Pipelines
        • BitBucket Pipelines
        • Buildkite
        • CircleCI
        • Drone CI
        • GitHub Actions
        • GitLab
        • Jenkins
        • Semaphore CI
        • TeamCity
        • Travis CI
        • Other CI Providers
    • Dashboard
    • Flaky Test Detection
    • Quarantining
    • PR Comments
    • Ticketing Integrations
      • Jira Integration
      • Linear Integration
      • Other Ticketing Platforms
    • Webhooks
      • Slack Integration
      • Microsoft Teams Integration
      • GitHub Issues Integration
      • Linear Integration
    • Uploader CLI Reference
  • Merge Queue
    • Overview
    • How does it work?
    • Setup
      • Quick Start
      • Settings
      • Integration for Slack
    • Concepts and Optimizations
      • Predictive Testing
      • Optimistic Merging
      • Pending Failure Depth
      • Anti-Flake Protection
      • Batching
      • Parallel Queues
        • Bazel
        • Nx
        • API
      • FAQ
    • Priority
    • Managing Merge Queue
      • Using the Merge UI
      • Metrics
      • Command Line
    • Webhooks
    • Reference
  • Code Quality
    • Overview
    • Why Metalinters?
      • How does it work?
      • Why Code Quality?
    • Setup & Installation
      • Initialize Trunk
      • Local Linting
      • Linting in CI
      • Nightly Report (Deprecated)
    • IDE Integration
      • VSCode
      • Neovim
      • GitHub Codespaces
    • Linters
      • Supported Linters
        • Actionlint
        • Ansible-lint
        • Autopep8
        • Bandit
        • Biome
        • Black
        • Brakeman
        • buf
        • Buildifier
        • cfnlint
        • Checkov
        • circleci
        • ClangFormat
        • clang-tidy
        • Clippy
        • cmake-format
        • codespell
        • cspell
        • cue-fmt
        • dart
        • deno
        • Detekt
        • djlint
        • dotenv-linter
        • dotnet-format
        • dustilock
        • ESLint
        • Flake8
        • git-diff-check
        • Gitleaks
        • Gofmt
        • gofumpt
        • goimports
        • gokart
        • golangci-lint
        • golines
        • google-java-format
        • graphql-schema-linter
        • hadolint
        • haml-lint
        • isort
        • iwyu
        • ktlint
        • kube-linter
        • markdown-link-check
        • markdown-table-prettify
        • Markdownlint
        • markdownlint-cli2
        • mypy
        • nancy
        • nixpkgs-fmt
        • opa
        • OSV-Scanner
        • Oxipng
        • perlcritic
        • perltidy
        • php-cs-fixer
        • phpstan
        • pmd
        • pragma-once
        • pre-commit-hooks
        • Prettier
        • prisma
        • psscriptanalyzer
        • Pylint
        • pyright
        • regal
        • remark-lint
        • renovate
        • rome
        • rubocop
        • Ruff
        • rufo
        • rustfmt
        • scalafmt
        • semgrep
        • ShellCheck
        • shfmt
        • sort-package-json
        • sourcery
        • sql-formatter
        • SQLFluff
        • sqlfmt
        • squawk
        • standardrb
        • stringslint
        • stylelint
        • stylua
        • SVGO
        • swiftformat
        • swiftlint
        • taplo
        • Terraform
        • terragrunt
        • terrascan
        • TFLint
        • tfsec
        • tofu
        • Trivy
        • Trufflehog
        • txtpbfmt
        • vale
        • Yamllint
        • yapf
      • Run Linters
      • Manage Linters
      • Configure Linters
      • Ignoring Issues and Files
      • Custom Linters
      • Shared Configs
      • Upgrades
    • Debugging
    • Licensing
  • CLI & API References
    • CLI Reference
      • Install
      • Getting Started
        • Code Quality
        • Merge Queue
        • Flaky Tests
        • Tools
        • Actions
          • Git Hooks
        • Announce
      • Compatibility
      • Caching
      • Commands Reference
        • Code Quality
        • Actions
        • Merge
      • Configuration
        • Plugins
          • Share Config Between Codebases
          • Exporting Linter Configs
        • Runtimes
        • Tools
        • Lint
          • Definitions
          • Commands
          • Output
          • Output Parsing
          • Files and Caching
          • Dependencies
          • Auto-Enable
        • Actions
          • Notifications
          • Logging and Troubleshooting
        • Merge
        • Telemetry
        • Per User Overrides
    • API Reference
      • Flaky Tests
      • Merge Queue
      • Webhooks Reference
  • Pricing & Security
    • Security
  • Billing
  • Community & Support
  • Links
    • Open App
    • Slack Community
    • Changelog
    • Feature Requests
On this page
  • Plugin Config Merging
  • Importing a Plugin Repository
  • Plugin Capabilities
  • Plugins Scope
  • Excluded Fields
Edit on GitHub
  1. CLI & API References
  2. CLI Reference
  3. Configuration

Plugins

Last updated 3 months ago

Plugin Config Merging

Trunk uses a plugin system where a root configuration is defined in the . You can import many plugin config sources, and fields defined at each level override the level above.

When plugin configs are merged, only fields defined in a config file are merged into the level above. You can define just the fields you wish to override in .trunk/trunk.yaml and .trunk/user.yaml.

When using trunk, you can merge several sets of configuration files with a trunk.yaml schema. Config merging proceeds as follows:

  1. Remote plugins sourced in .trunk/trunk.yaml (and .trunk/user.yaml). Plugins are sourced in the order they're defined, with later plugins overriding those defined before it. The plugin is implicitly sourced first.

  2. Your repo level .trunk/trunk.yaml file, complete with a CLI version and any definitions or enables. Configurations defined here override what's defined in the remote plugins.

  3. Optionally, .trunk/user.yaml, a local git-ignored file where users can provide their own overrides.

Additionally, any files enumerated in the lint exported_configs section are symlinked from their relevant plugin into the root of the workspace when an applicable linter is run with trunk check.

Importing a Plugin Repository

By default, trunk imports the trunk-io/plugins repository. To import a repo add it to the plugins.sources list. Each repo requires a URI and ref.

plugins:
  sources:
    - id: trunk
      uri: https://github.com/trunk-io/plugins
      ref: v1.2.6
Field
Description

id

unique identifier for this repository

uri

address used to clone the target repository

ref

commit id or tag to checkout. Do not use branch names, as these can be unstable

local

path to local (on-disk) repository. Takes precedence over uri/ref if defined

import_to_global (default: true)

import content into the global namespace. If set to false actions and linters defined in the plugin must be referenced by <plugin_id>.<name>

Plugin Capabilities

Add a plugin to your trunk.yaml file

To add a plugin from GitHub:

trunk plugins add https://github.com/trunk-io/plugins --id=trunk

To add a plugin from GitHub at a specific version:

trunk plugins add https://github.com/trunk-io/plugins v1.2.6 --id=trunk

To add a plugin from a local repository:

trunk plugins add /home/user/self/hello-world --id=hello-world

Note that when specifying a remote plugin, the ref field must be a tag or SHA.

Plugins Scope

Plugins are merged serially, in the order that they are sourced, and can override almost any Trunk configuration. This allows organizations to provide a set of overrides and definitions in one central place.

For instance, you can create your own my-plugins repository with plugin.yaml:

version: 0.1
lint:
  definitions:
    - name: trufflehog
      commands:
        - name: lint
          # override trufflehog to use '--only-verified'
          run: trufflehog filesystem --json --fail --only-verified ${target}
  enabled:
    - ruff@0.0.256

sourced in a .trunk/trunk.yaml file from another repository as follows:

version: 0.1
plugins:
  sources:
    - id: trunk
      uri: https://github.com/trunk-io/plugins
      ref: v1.2.6
    - id: my-plugins
      local: ../my-plugins

When a user runs trunk in the sourcing repository, they will already have ruff enabled, along with the trufflehog override from the my-plugins repository.

Note that private GitHub plugin repositories are not currently supported.

Excluded Fields

Plugin sources, as well as the cli version, are not merged from plugin repositories to ensure that config merging occurs in a predictable, stable fashion.

Any configuration used in trunk.yaml can also be used in a plugin repository, with . A plugin repository must have one root level plugin.yaml and can have any number of other plugin.yaml files in other subdirectories. These configuration files are then merged into one composite plugin configuration.

The most common use for a plugin repository is to define custom linters, actions, or tools. But they can also be used to define a common set of shared tools across an organization. For more info, see .

The root plugin.yaml file may also have a required_trunk_version field which governs compatibility when between CLI versions.

trunk-io/plugin repository
trunk
organization configs
upgrading
some exceptions