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.3
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 the linters and actions exported by that repository are enumerated. 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.
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 trunk-plugins https://github.com/trunk-io/plugins
To add a plugin from GitHub at a specific version:
trunk plugins add trunk-plugins https://github.com/trunk-io/plugins v0.0.5
To add a plugin from a local repository:
trunk plugins add hello-world /home/user/self/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 that 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.3
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.
Updated 18 days ago