Buildkite Plugin Linter

A linter for your Buildkite plugins, used by the plugin-linter Buildkite plugin ✨

Features:

• Checks for a plugin.yml file (and validates it against the plugin.yml JSON schema)
• Checks that all readme examples match the plugin’s schema
• Check the readme version numbers are up-to-date with the latest plugin version
• Machine-parseable TAP output

Further reading and tools:

• JSON Schema
• JSON Schema Lint

Configuration

Options available on the executable as long-form switches (--OPTION) can also be passed through as environment variables with the PLUGIN_ prefix (PLUGIN_OPTION).

Required

id (string, PLUGIN_ID)

This is the id of the plugin to be validated. It is used to search for and validate examples.

path (string, PLUGIN_PATH)

Where the plugin to lint can be found.

Optional

readme (string, PLUGIN_README)

The name of the file to validate examples on.

Default: README.md

skip-invalid (boolean, PLUGIN_SKIP_INVALID)

Invalid versions are normally reported as failures, turning on this option would change that behaviour.

Default: false

Usage

You should use this tool via the Linter Plugin in your plugin's pipeline.

Alternatively, you can add it to your docker-compose.yml file and then use docker-compose run --rm lint:

services:
  lint:
    image: buildkite/plugin-linter
    command: ['--id', 'my-org/my-plugin']
    volumes:
      - ".:/plugin"

or you can run it locally on the command line:

docker run \
  -it \
  --rm \
  -v "$(pwd):/plugin" \
  buildkite/plugin-linter \
    --id my-org/my-plugin \
    --path README.md

If your plugin examples use a full git URL, such as ssh://[email protected]/my-org/example-buildkite-plugin, then you should specify the full git URL in the id argument.

Roadmap / TODO

• Check that all the config options in the readme exist in the configuration schema
• Check that all the options in the configuration schema exist in the readme
• Warn about undocumented config options found in source code

Contributions welcome! ❤️

Developing/testing

If you have Node installed:

npm install
npm test
bin/lint --help

Code style is validated using JavaScript Standard Style.

To run the tests using Docker Compose:

# Run the tests
docker-compose run --rm linter
# Run the lint command
docker-compose run --rm linter lint --help

Releasing

• Master is built and tested automatically, and pushes a new image to buildkite/plugin-linter on Docker Hub

License

MIT (see LICENSE)