eslint-plugin-woodpecker

ESLint rules for Woodpecker CI (including shell commands).

Installation

From your project root:

npm i -D eslint-plugin-woodpecker

Add a bundled config to your eslint.config.*js:

...
import woodpecker from 'eslint-plugin-woodpecker'

export default [
    // other configs
    woodpecker.configs.recommended
]

Available bundles: recommended, strict (everything), problem (deterministic bugs only)

Note: Rule config is either a severity string ('off', 'warn', 'error') or an array [severity, options] when the rule accepts options:

...
import woodpecker from 'eslint-plugin-woodpecker'

export default [
    // other configs
    {
        ...woodpecker.configs.strict,
        rules: {
            ...woodpecker.configs.strict.rules,
            'woodpecker/require-event-filter': 'off',  // selectively disable rule
            'woodpecker/shellcheck-commands': ['error', { ignoreCodes: ['SC2086'] }]  // selectively tweak rule
        }
    }
]

Incorrect code

  steps:
    - name: build
      image: node:20
!   - name: build
      image: alpine

Correct code

  steps:
    - name: build
      image: node:20
-   - name: build
+   - name: deploy
      image: alpine

When not to use it

If you intentionally duplicate step names.

Introduced in

v1.0.0 (October 17, 2026)

See also

•  Woodpecker — Workflow syntax

Back to index ↑

Incorrect code

  steps:
    build:
      image: node:20

Correct code

+ when:
+   event: push
  steps:
    build:
      image: node:20

When not to use it

If you intentionally trigger your pipeline on every event, or if you filter per-step.

Introduced in

v1.0.0 (October 17, 2026)

See also

•  Woodpecker — when conditions

Back to index ↑

• ignoreCodes (default []) – SC codes to suppress project-wide (e.g. ['SC2086'])
• enableChecks (default []) – optional ShellCheck checks to enable (e.g. ['avoid-nullary-conditions'])
• shell (default 'sh') – shell dialect to assume ('ash', 'bash', 'busybox', 'dash', 'ksh', 'sh')
• shellcheckPath (default null) – explicit path to the shellcheck binary (when omitted, resolves from PATH)

Incorrect code

  steps:
    build:
      image: node:20
      commands:
!       - 'foo="bar baz"; echo $foo'

Correct code

  steps:
    build:
      image: node:20
      commands:
-       - 'foo="bar baz"; echo $foo'
+       - 'foo="bar baz"; echo "$foo"'

When not to use it

If you don't have the ShellCheck binary installed, or you don't want shell linting.

Introduced in

v1.0.0 (October 17, 2026)

See also

•  ShellCheck — Wiki

Back to index ↑

Incorrect code

  steps:
    build:
      image: node:20
    deploy:
      image: alpine
!     depends_on: [test]

Correct code

  steps:
    build:
      image: node:20
    deploy:
      image: alpine
-     depends_on: [test]
+     depends_on: [build]

When not to use it

If you generate depends_on at build time.

Introduced in

v1.0.0 (October 17, 2026)

See also

•  Woodpecker — Workflow syntax

Back to index ↑

Incorrect code

  steps:
    build:
      commands: ['npm test']

Correct code

  steps:
    build:
+     image: node:20
      commands: ['npm test']

When not to use it

If you use a modified schema.

Introduced in

v1.0.0 (October 17, 2026)

See also

•  Woodpecker — Workflow syntax
•  Woodpecker — CLI reference

Back to index ↑

Shield embed

HTML

<a target="_blank" href="https://codeberg.org/adamlui/eslint-plugin-woodpecker/#readme">
    <img height=32 alt="[Linted by eslint-plugin-woodpecker]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--woodpecker-black?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge"></a>

Markdown

[![[Linted by eslint-plugin-woodpecker]](https://img.shields.io/badge/Linted_by-eslint--plugin--woodpecker-black?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge)](https://codeberg.org/adamlui/eslint-plugin-woodpecker/#readme)

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

Related

eslint-plugin-chrome-extensions

Install / Readme / Supported rules

eslint-plugin-constructors

Install / Readme / Supported rules

eslint-plugin-greasemonkey

Install / Readme / Supported rules

Latest releases / Report a bug / More packages by author / Back to top ↑