jenkinsfilelint 1.4.0__tar.gz

jenkinsfilelint-1.4.0/.env.example

@@ -0,0 +1,6 @@
+# Copy this file to .env and fill in your Jenkins credentials.
+# .env is git-ignored and will never be committed.
+
+JENKINS_URL=http://localhost:8080
+JENKINS_USER=your-username
+JENKINS_TOKEN=your-api-token

jenkinsfilelint-1.4.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @jenkinsci/jenkinsfilelint-developers

jenkinsfilelint-1.4.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: "monthly"
+    groups:
+      github-action:
+        patterns:
+          - "*"
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: "monthly"
+    groups:
+      pip:
+        patterns:
+          - "*"

jenkinsfilelint-1.4.0/.github/workflows/main.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
+      with:
+        fetch-depth: 0  # Required for setuptools-scm
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548  # v6.1.0
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Test CLI installation
+      run: |
+        jenkinsfilelint --help
+
+    - name: Run unit tests
+      run: |
+        pytest tests/ -v --cov=jenkinsfilelint --cov-report=term-missing --cov-report=xml
+      shell: bash
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2  # v6.0.0
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage.xml

jenkinsfilelint-1.4.0/.github/workflows/release-drafter.yml

@@ -0,0 +1,22 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - "main"
+  # allowing to run manually
+  workflow_dispatch:
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required to create/update the release
+      contents: write
+      # Required for autolabeler to add labels to PRs
+      pull-requests: write
+      
+    steps:
+      - uses: release-drafter/release-drafter@v7
+        with:
+          config-name: github:shenxianpeng/.github:/.github/release-drafter.yml

jenkinsfilelint-1.4.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release Package
+
+on:
+  release:
+    branches: [main]
+    types: [published]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/jenkinsfilelint
+
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      with:
+        fetch-depth: 0  # needed for setuptools_scm to derive version from git tags
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+      with:
+        python-version: '3.x'
+    - name: Install build tools
+      run: python -m pip install --upgrade pip build twine
+    - name: Build distribution
+      run: python -m build
+    - name: Check distribution
+      run: twine check dist/*
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0

jenkinsfilelint-1.4.0/.gitignore

@@ -0,0 +1,31 @@
+# Environment
+.env
+
+# Python virtual environment
+venv/
+.venv/
+
+# Python compiled files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+*.log
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~

jenkinsfilelint-1.4.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+ci:
+  skip: [jenkinsfilelint]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: debug-statements
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.6
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: local
+    # This is a "local" hook to run jenkinsfilelint
+    hooks:
+      - id: jenkinsfilelint
+        name: jenkinsfilelint
+        description: Lint Jenkinsfiles and Groovy files.
+        entry: jenkinsfilelint
+        language: python
+        additional_dependencies: ['requests']
+        files: (?i)^(.*/)?(Jenkinsfile[^/]*|.*\.groovy)$
+        exclude: ^jenkinsfilelint/
+        pass_filenames: true
+        verbose: true
+        stages: [manual]  # pre-commit run jenkinsfilelint --all-files --hook-stage manual

jenkinsfilelint-1.4.0/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: jenkinsfilelint
+  name: jenkinsfilelint
+  description: Lint Jenkinsfiles and Groovy files.
+  entry: jenkinsfilelint
+  language: python
+  types: [file]
+  files: ^.*(Jenkinsfile.*|.*\.groovy)$
+  require_serial: true

jenkinsfilelint-1.4.0/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Contributions are welcome! Here's how to get started.
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+```
+
+Run pre-commit before submitting:
+
+```bash
+pre-commit run --all-files
+```
+
+## Testing
+
+```bash
+pytest tests/ -v --cov=jenkinsfilelint
+```
+
+## Conventions
+
+- Follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, etc.)
+- Keep PRs focused — one logical change per PR.
+- Update the README if your change affects usage or configuration.

jenkinsfilelint-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Xianpeng Shen
+
+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.

jenkinsfilelint-1.4.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: jenkinsfilelint
+Version: 1.4.0
+Summary: A Jenkinsfile linter that validates Jenkinsfiles using Jenkins API
+Author-email: Xianpeng Shen <xianpeng.shen@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shenxianpeng/jenkinsfilelint
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# 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)
+[![PyPI version](https://img.shields.io/pypi/v/jenkinsfilelint )](https://pypi.org/project/jenkinsfilelint/)
+
+Catch Jenkinsfile syntax errors before they break your CI.
+
+`jenkinsfilelint` validates Jenkinsfiles through your real Jenkins instance and works as a CLI or pre-commit hook.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Security Notes](#security-notes)
+- [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.
+
+### Including Only Specific Files
+
+Use the `--include` option to validate only files that match specified patterns (whitelist approach). Files not matching any include pattern are silently skipped:
+
+```bash
+# Only validate Jenkinsfiles (files starting with "Jenkinsfile")
+jenkinsfilelint --include 'Jenkinsfile*' Jenkinsfile Jenkinsfile.prod src/Utils.groovy
+
+# Only validate pipeline groovy files in a specific folder
+jenkinsfilelint --include 'pipelines/*.groovy' pipelines/deploy.groovy src/Utils.groovy
+
+# Use multiple include patterns
+jenkinsfilelint --include 'Jenkinsfile*' --include 'pipelines/*.groovy' \
+  Jenkinsfile pipelines/deploy.groovy src/Utils.groovy
+```
+
+The `--include` and `--skip` options can be combined: `--include` first narrows the set of files to consider, then `--skip` further excludes files within that set.
+
+### 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"]
+```
+
+To validate only specific files:
+
+```yaml
+repos:
+  - repo: https://github.com/shenxianpeng/jenkinsfilelint
+    rev: # or specific version tag
+    hooks:
+      - id: jenkinsfilelint
+        args: ["--include=Jenkinsfile*", "--include=pipelines/*.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
+```
+
+## Security Notes
+
+- Do not commit Jenkins tokens to `.pre-commit-config.yaml` or `.env` .
+- Prefer environment variables or local secret managers.
+- Avoid using administrator tokens for local linting.
+
+## How It Works
+
+> **What it is:** A Jenkinsfile syntax gate — not a Groovy formatter, not a static analyzer.
+
+The linter sends the Jenkinsfile to your Jenkins instance's `/pipeline-model-converter/validate` endpoint for validation. If it passes here, it will pass on the server. Jenkins credentials (URL, username, and API token) are required.
+
+## Requirements
+
+- Python 3.10+
+- Jenkins server with Pipeline plugin installed
+
+## License
+
+MIT License

jenkinsfilelint-1.4.0/README.md

@@ -0,0 +1,191 @@
+# 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)
+[![PyPI version](https://img.shields.io/pypi/v/jenkinsfilelint )](https://pypi.org/project/jenkinsfilelint/)
+
+Catch Jenkinsfile syntax errors before they break your CI.
+
+`jenkinsfilelint` validates Jenkinsfiles through your real Jenkins instance and works as a CLI or pre-commit hook.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Security Notes](#security-notes)
+- [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.
+
+### Including Only Specific Files
+
+Use the `--include` option to validate only files that match specified patterns (whitelist approach). Files not matching any include pattern are silently skipped:
+
+```bash
+# Only validate Jenkinsfiles (files starting with "Jenkinsfile")
+jenkinsfilelint --include 'Jenkinsfile*' Jenkinsfile Jenkinsfile.prod src/Utils.groovy
+
+# Only validate pipeline groovy files in a specific folder
+jenkinsfilelint --include 'pipelines/*.groovy' pipelines/deploy.groovy src/Utils.groovy
+
+# Use multiple include patterns
+jenkinsfilelint --include 'Jenkinsfile*' --include 'pipelines/*.groovy' \
+  Jenkinsfile pipelines/deploy.groovy src/Utils.groovy
+```
+
+The `--include` and `--skip` options can be combined: `--include` first narrows the set of files to consider, then `--skip` further excludes files within that set.
+
+### 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"]
+```
+
+To validate only specific files:
+
+```yaml
+repos:
+  - repo: https://github.com/shenxianpeng/jenkinsfilelint
+    rev: # or specific version tag
+    hooks:
+      - id: jenkinsfilelint
+        args: ["--include=Jenkinsfile*", "--include=pipelines/*.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
+```
+
+## Security Notes
+
+- Do not commit Jenkins tokens to `.pre-commit-config.yaml` or `.env` .
+- Prefer environment variables or local secret managers.
+- Avoid using administrator tokens for local linting.
+
+## How It Works
+
+> **What it is:** A Jenkinsfile syntax gate — not a Groovy formatter, not a static analyzer.
+
+The linter sends the Jenkinsfile to your Jenkins instance's `/pipeline-model-converter/validate` endpoint for validation. If it passes here, it will pass on the server. Jenkins credentials (URL, username, and API token) are required.
+
+## Requirements
+
+- Python 3.10+
+- Jenkins server with Pipeline plugin installed
+
+## License
+
+MIT License

jenkinsfilelint-1.4.0/jenkinsfilelint/__init__.py

@@ -0,0 +1,9 @@
+"""Jenkinsfile linter package."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("jenkinsfilelint")
+except PackageNotFoundError:
+    # Package is not installed
+    __version__ = "0.0.0.dev0"