jenkinsfilelint 1.2.0
A Jenkinsfile linter that validates Jenkinsfiles using Jenkins API
Requires Python: >=3.6

# Jenkinsfile Lint

[![CI](https://github.com/shenxianpeng/jenkinsfilelint/actions/workflows/main.yml/badge.svg)](https://github.com/shenxianpeng/jenkinsfilelint/actions/workflows/main.yml)
[![codecov](https://codecov.io/gh/shenxianpeng/jenkinsfilelint/graph/badge.svg?token=Z9UTXBL2XG)](https://codecov.io/gh/shenxianpeng/jenkinsfilelint)

A Python-based Jenkinsfile linter that validates Jenkinsfiles using Jenkins API.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [How It Works](#how-it-works)
- [Requirements](#requirements)
- [License](#license)

## Features

- Validates Jenkinsfiles using Jenkins REST API
- Works as a pre-commit hook
- Supports both command-line usage and environment variables for configuration
- Requires Jenkins credentials for validation
- Supports skipping files that are not Jenkins pipelines (e.g., pure Groovy helper classes)

## Installation

### Using pip

```bash
pip install jenkinsfilelint
```

### Using pre-commit

Add this to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/shenxianpeng/jenkinsfilelint
    rev: # or specific version tag
    hooks:
      - id: jenkinsfilelint
```

## Usage

> [!IMPORTANT]
> jenkinsfilelint requires Jenkins credentials to be set via environment variables for validation:
>
> - `JENKINS_URL`: Your Jenkins server URL (required)
> - `JENKINS_USER`: Your Jenkins username (required unless anonymous access is enabled)
> - `JENKINS_TOKEN`: Your Jenkins API token (required unless anonymous access is enabled)

### Command Line

Validation requires Jenkins credentials. Set them using environment variables:

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

jenkinsfilelint path/to/Jenkinsfile
```

Or using command-line arguments:

```bash
jenkinsfilelint path/to/Jenkinsfile \
  --jenkins-url https://your-jenkins-instance.com \
  --username your-username \
  --token your-api-token
```

Validate multiple files:

```bash
jenkinsfilelint Jenkinsfile Jenkinsfile.prod tests/Jenkinsfile
```

### Skipping Files

In Jenkins shared libraries, some Groovy files are pure Groovy helper classes, not Jenkins pipeline scripts. Use the `--skip` option to exclude files from validation:

```bash
# Skip a specific file pattern
jenkinsfilelint --skip '*/src/*.groovy' Jenkinsfile src/Utils.groovy

# Skip multiple patterns
jenkinsfilelint --skip '*/src/*.groovy' --skip 'vars/*.groovy' Jenkinsfile src/Utils.groovy vars/deploy.groovy
```

The `--skip` option accepts glob patterns and can be used multiple times.

### Pre-commit Hook

Create or update `.pre-commit-config.yaml` in your repository:

```yaml
repos:
  - repo: https://github.com/shenxianpeng/jenkinsfilelint
    rev: # or specific version tag
    hooks:
      - id: jenkinsfilelint
```

Or using command-line arguments:

```yaml
repos:
  - repo: https://github.com/shenxianpeng/jenkinsfilelint
    rev: # or specific version tag
    hooks:
      - id: jenkinsfilelint
        args: ["--jenkins-url=https://your-jenkins-instance.com", "--username=your-username", "--token=your-api-token"]
```

To skip certain files (e.g., pure Groovy classes in Jenkins shared libraries):

```yaml
repos:
  - repo: https://github.com/shenxianpeng/jenkinsfilelint
    rev: # or specific version tag
    hooks:
      - id: jenkinsfilelint
        args: ["--skip=*/src/*.groovy", "--skip=vars/*.groovy"]
```

> [!WARNING]
> Using `args` to pass credentials directly in the configuration file is not recommended for security reasons.
> Consider using environment variables instead. For more details, see [pre-commit/pre-commit#758](https://github.com/pre-commit/pre-commit/issues/758#issuecomment-505935221).

Then install the pre-commit hook:

```bash
pre-commit install
```

## How It Works

The linter sends the Jenkinsfile to your Jenkins instance's `/pipeline-model-converter/validate` endpoint for validation. Jenkins credentials (URL, username, and API token) are required.

## Requirements

- Python 3.6+
- Jenkins server with Pipeline plugin installed

## License

MIT License