jenkinsfilelint 1.4.1

A Jenkinsfile linter that validates Jenkinsfiles using Jenkins API

Jenkinsfile Lint

Catch Jenkinsfile syntax errors before they break your CI.

jenkinsfilelint sends your Jenkinsfiles to your Jenkins server's /pipeline-model-converter/validate endpoint for real syntax validation. It's primarily a pre-commit hook, but also works as a CLI tool.

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

Table of Contents

• Quick Start
• Usage
  • Pre-commit Hook
  • CLI
  • Filtering files
• Configuration
• Security
• How It Works
• Requirements
• Contributing
• License

Quick Start

# .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

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

Usage

Pre-commit Hook

Once installed, every commit that touches a Jenkinsfile is validated:

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

If the file has a syntax error the commit is blocked:

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, re-commit, and it passes.

CLI

pip install jenkinsfilelint

jenkinsfilelint Jenkinsfile
jenkinsfilelint Jenkinsfile Jenkinsfile.prod tests/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 *

* Only required if your Jenkins requires authentication.

[!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.

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 is a syntax gate — it checks that your Declarative Pipeline syntax is valid.

1. Reads the local Jenkinsfile.
2. POSTs it to <JENKINS_URL>/pipeline-model-converter/validate.
3. Jenkins parses the Pipeline and returns "ok" or errors.
4. Errors are printed and the tool exits non-zero.

It only answers: "Will Jenkins accept this syntax?"

Requirements

• Python 3.10+
• Jenkins server with the Pipeline plugin

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.