Overview
Plugins are a mechanism to share your linter and action definitions with the community.
A plugins repository provides users the ability to expand the core capabilities of trunk check and trunk actions. A plugin repo contains a set of custom linter and action definitions.
Importing a plugin repository
By default trunk imports the trunk-io/plugins repository. To import a repo add it to the plugins
list. Each repo requires a URI and ref.
plugins:
sources:
- id: trunk
uri: https://github.com/trunk-io/plugins
ref: v0.0.15
import_to_global: true
field | description |
---|---|
id | unique identifier for this repository |
uri | address used to clone the target repository |
ref | commit id or tag to checkout |
local | path to local (on-disk) repository |
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} |
Custom linters and actions
The root of a plugin repository has a plugin.yaml
file where new linters and actions can be defined. The plugin.yaml
file looks a lot like a standard trunk.yaml
file with the addition of a special field required_trunk_version
which indicates the minimum trunk version required to use that repo. Plugin repositories can have multiple plugin.yaml
files, which all get merged into one composite plugin configuration.
Beyond the required_trunk_version
the definition of an action or linter is no different in a plugin repository.
Add a plugin to your trunk.yaml
file
trunk.yaml
fileTo 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 v0.0.16 --id=trunk
To add a plugin from a local repository:
trunk plugins add /home/user/self/hello-world --id=hello-world
Contributing to a published plugin repository
Let's quickly walk through how to modify/add to an existing remote repository. In this case we'll make an edit to the trunk-io/plugins repository.
- Clone the plugins repository to your local disk -
git clone [email protected]:trunk-io/plugins.git
- Add a
local
field to your trunk.yaml file to point your usage of the plugin repo to your local instance. When a plugin source includes alocal
field, it will supercede the remote uri/ref values. This makes it easy to quickly iterate locally before pushing changes to the cloud.
plugins:
sources:
- id: trunk
uri: https://github.com/trunk-io/plugins
ref: v0.0.15
local: /home/eli/Github/plugins
- Edit the entries in the local version of the plugin repository.
- Push your changes to the remote version of the plugin repo.
- Remove the
local
field and point theref
of the remote repo to the newly landed changes.
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:
- [email protected]
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: v0.0.15
- id: my-plugins
local: ../my-plugins
When a user runs trunk
in the sourcing repository, they will already have ruff enabled, along with
any overrides and definitions enumerated in 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.
Updated about 1 month ago