Catch Jenkinsfile Errors Before Commit with jenkinsfilelint – A Python Linter

Hello everyone! I want to share an open‑source utility I recently developed: jenkinsfilelint .

Why create this tool?

Anyone who writes Jenkins Pipelines has likely experienced the following painful workflow:

Write a Jenkinsfile with great effort.

Commit the code and push it to the repository.

Watch Blue Ocean or the console waiting for the build to start.

Crash! After a few seconds the build fails because of a missing brace } or a typo.

Fix the code → commit again → wait → hope it works.

Existing Jenkinsfile checkers were either hard to configure or could not integrate well with a pre‑commit workflow, so I decided to build my own.

What is jenkinsfilelint?

jenkinsfilelint

is a Python‑based command‑line tool that validates Jenkinsfile syntax before code is committed. It calls Jenkins’s native API ( /pipeline-model-converter/validate) to ensure the validation results match the actual runtime parser.

Core Features

Based on Jenkins API : Uses the official validation endpoint, providing accurate results with line numbers.

Perfect pre‑commit support : Easily integrates into Git hooks to run automatically on each commit.

Flexible configuration : Jenkins URL and credentials can be set via environment variables or command‑line arguments.

Smart filtering : When a repository contains Groovy helper files (not pipeline scripts), the --skip option can exclude them to avoid false positives.

How to Use

1. Install

pip install jenkinsfilelint

2. Integrate with pre‑commit (strongly recommended)

Create or edit a .pre-commit-config.yaml in the project root and add:

repos:
- repo: https://github.com/shenxianpeng/jenkinsfilelint
  rev: v1.2.0  # use the latest tag
  hooks:
  - id: jenkinsfilelint

Then install the hook:

pre-commit install

3. Configure credentials

The validator needs to call the Jenkins API, so you must provide the Jenkins URL and access credentials. Do NOT hard‑code username/password; use environment variables instead:

# Linux/macOS
export JENKINS_URL=https://your-jenkins-instance.com
export JENKINS_USER=your-username
export JENKINS_TOKEN=your-api-token

After configuration, when you run git commit, jenkinsfilelint will automatically check any changed Jenkinsfile.

Command‑line manual checks

You can also run the tool directly to validate specific files:

# Check a single file
jenkinsfilelint Jenkinsfile

# Check multiple files
jenkinsfilelint Jenkinsfile Jenkinsfile.prod

# Skip files matching a pattern (e.g., Groovy files in src/)
jenkinsfilelint --skip '*/src/*.groovy' Jenkinsfile src/Utils.groovy

Final Notes

The project is published on PyPI, so you can install and try it immediately. If you’re tired of Jenkinsfile errors breaking your builds after commit, give jenkinsfilelint a try. Contributions, issues, and pull requests are welcome.

https://github.com/shenxianpeng/jenkinsfilelint