jenkinsfilelint 1.5.0

A Jenkinsfile linter that validates Jenkinsfiles using Jenkins API

Jenkinsfile Lint

Catch Jenkinsfile syntax errors before they break your CI.

jenkinsfilelint validates your Declarative Pipeline syntax via Jenkins's /pipeline-model-converter/validate endpoint. It's primarily a pre-commit hook, but also works as a standalone CLI tool.

📖 Read the official blog post for the story behind this tool.

Table of Contents

• Quick Start
• Pre-commit Hook
  • Remote mode (with a Jenkins server)
  • Local mode (with Docker, no Jenkins server needed)
  • What happens on commit
• CLI
• Filtering files
• Configuration
  • Local Docker image
• Security
• How It Works
• Requirements
• Contributing
• License

Quick Start

pip install jenkinsfilelint

Then add the pre-commit hook (see below) or use the CLI directly.

Pre-commit Hook

Add the hook to your .pre-commit-config.yaml and install. Once configured, every commit that touches a Jenkinsfile is automatically validated.

Remote mode (with a Jenkins server)

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/jenkinsci/jenkinsfilelint
    rev: # use the latest or a specific version, e.g. v1.4.0
    hooks:
      - id: jenkinsfilelint

Set credentials via environment variables, then install:

export JENKINS_URL=https://jenkins.example.com
export JENKINS_USER=your-username
export JENKINS_TOKEN=your-api-token

pip install pre-commit
pre-commit install

Local mode (with Docker, no Jenkins server needed)

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/jenkinsci/jenkinsfilelint
    rev: # use the latest or a specific version, e.g. v1.4.0
    hooks:
      - id: jenkinsfilelint
        args: ["--local"]

Docker (or Podman) is the only requirement — no credentials needed:

pip install pre-commit
pre-commit install

The first commit pulls a minimal Jenkins container (~20–40s cold start). Subsequent commits reuse the running container and complete in milliseconds.

[!IMPORTANT] Local mode validates vanilla Declarative Pipeline syntax only. If your production Jenkins has plugins that provide custom options, agents, or steps (e.g., custom shared libraries), local mode may not catch errors related to those plugins. For authoritative validation, use remote mode pointing at your real Jenkins server.

In short: --local = fast syntax gate, remote = authoritative validation.

When you're done, stop the container:

jenkinsfilelint server stop

What happens on commit

A valid file passes silently:

git commit -m "Update Jenkinsfile"
jenkinsfilelint..........................................................Passed

A syntax error blocks the commit with a clear message:

git commit -m "Update Jenkinsfile"
jenkinsfilelint..........................................................Failed
- hook id: jenkinsfilelint
- exit code: 1

Errors encountered validating Jenkinsfile:
WorkflowScript: 17: Expected a step @ line 17, column 11.
             test
             ^

Fix the error and re-commit.

CLI

You can also run jenkinsfilelint directly on any file:

pip install jenkinsfilelint

jenkinsfilelint Jenkinsfile
jenkinsfilelint Jenkinsfile Jenkinsfile.prod tests/Jenkinsfile
jenkinsfilelint --local Jenkinsfile

Filtering files

Use --include (whitelist) and --skip (blacklist) to control which files are validated:

# Only validate Jenkinsfiles
jenkinsfilelint --include 'Jenkinsfile*' Jenkinsfile src/Utils.groovy

# Exclude shared-library helper classes
jenkinsfilelint --skip '*/src/*.groovy' --skip 'vars/*.groovy' Jenkinsfile src/Utils.groovy

These work in pre-commit too:

Exclude non-pipeline Groovy files (shared library helpers):

- id: jenkinsfilelint
  args: ["--skip=*/src/*.groovy", "--skip=vars/*.groovy"]

Only validate files matching specific patterns:

- id: jenkinsfilelint
  args: ["--include=Jenkinsfile*", "--include=pipelines/*.groovy"]

You can also combine both — --include narrows first, then --skip removes from that set:

- id: jenkinsfilelint
  args: ["--include=Jenkinsfile*", "--skip=*/src/*.groovy"]

Configuration

Supply credentials via environment variables (recommended) or CLI flags:

Env Variable	CLI Flag	Required
JENKINS_URL	--jenkins-url	Yes *
JENKINS_USER	--username	No **
JENKINS_TOKEN	--token	No **
JENKINSFILELINT_SERVER_IMAGE	—	No

* Not required in --local mode. ** Only required if your Jenkins requires authentication (not used in --local mode).

[!TIP] Even if your Jenkins allows anonymous access for validation, using an API token is recommended for production setups.

CLI flags override env vars. There is no config file.

Local Docker image

By default, --local mode uses the official image ghcr.io/jenkinsci/jenkinsfilelint-server:latest. You can override this with the JENKINSFILELINT_SERVER_IMAGE environment variable if you maintain a custom build.

Security

[!WARNING] Never hardcode credentials in config files — use environment variables.

• Never put --token or --username in .pre-commit-config.yaml — use environment variables.
• Use an API token, not your password.
• A regular user token with read access is sufficient — no need for admin privileges.

How It Works

jenkinsfilelint POSTs your Jenkinsfile to Jenkins's /pipeline-model-converter/validate endpoint and reports whether the syntax is valid. That's it — it only answers: "Will Jenkins accept this syntax?"

• Remote mode: validates against your existing Jenkins server using the URL and credentials you configure.
• Local mode (--local): automatically starts a lightweight Jenkins container (via Docker or Podman) and validates against it. The container is reused across runs for near-instant validation.

Requirements

• Python 3.10+
• For remote mode: a Jenkins server with the Pipeline plugin installed
• For --local mode: Docker or Podman

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.