A comprehensive GitHub Action for Python code quality enforcement. Runs Pylint, Black, and MyPy with automatic badge generation and detailed reporting.

• 🐍 Flexible Python version support - Specify any Python version using actions/setup-python
• 📦 Custom requirements - Install additional dependencies from a requirements file
• 🔍 Comprehensive linting - Run Pylint, Black, and MyPy in a single action
• 📊 Detailed reporting - View results in GitHub Actions summary
• 🏅 Automatic badge generation - Creates and commits SVG badges for each linter
• ⚙️ Highly configurable - Customize options for each linting tool

• Your repository must contain Python code
• For badge commits: the workflow needs contents: write permission

name: Python Lintingon: [push, pull_request]jobs:
lint:
runs-on: ubuntu-latestpermissions:
contents: write # Required for badge commitssteps:
- uses: actions/checkout@v4
- name: Python Lintinguses: thoughtparametersllc/python-linting@v1

name: Python Lintingon: [push, pull_request]jobs:
lint:
runs-on: ubuntu-latestpermissions:
contents: writesteps:
- uses: actions/checkout@v4
- name: Python Lintinguses: thoughtparametersllc/python-linting@v1with:
python-version: '3.11'requirements-file: 'requirements.txt'pylint-options: '--max-line-length=120 --disable=C0111'black-options: '--line-length=120'mypy-options: '--strict --ignore-missing-imports'commit-badges: 'true'badge-directory: '.github/badges'

- name: Python Lintinguses: thoughtparametersllc/python-linting@v1with:
python-version: '3.10'# Always quote version numberscommit-badges: 'false'# Disable automatic badge commits

name: Python Lintingon: [push, pull_request]jobs:
lint:
runs-on: ubuntu-lateststrategy:
matrix:
python-version: ['3.9', '3.10', '3.11', '3.12']steps:
- uses: actions/checkout@v4
- name: Python Lintinguses: thoughtparametersllc/python-linting@v1with:
python-version: ${{ matrix.python-version }}commit-badges: ${{ matrix.python-version == '3.11' && 'true' || 'false' }} # Only the Python 3.11 job commits badges

This action does not produce any outputs. Results are displayed in the GitHub Actions summary and as SVG badges (if enabled).

When commit-badges is set to true (default), the action automatically generates and commits three SVG badge files to your repository:

• {badge-directory}/pylint.svg - Pylint status badge
• {badge-directory}/black.svg - Black status badge
• {badge-directory}/mypy.svg - MyPy status badge

Add these badges to your README.md to show linting status:

![Pylint](.github/badges/pylint.svg)![Black](.github/badges/black.svg)![MyPy](.github/badges/mypy.svg)

• 🟢 Green (success) - No issues found
• 🔴 Red (failure) - Issues detected

This action requires the following permissions:

permissions:
contents: write # Required only if commit-badges is 'true'

If you set commit-badges: 'false', you can use:

permissions:
contents: read

Issue: The action fails to commit badges back to the repository.

Solutions:

• Ensure contents: write permission is set in your workflow
• Verify that branch protection rules allow the github-actions[bot] to push
• Check that the badge directory exists or can be created

Issue: Pylint, Black, or MyPy commands fail with "command not found".

Solutions:

• Ensure Python is properly set up (the action handles this automatically)
• Check that the Python version you specified is available
• Review the "Install Linting Tools" step logs for errors

Issue: Additional requirements cannot be installed.

Solutions:

• Verify the requirements-file path is correct relative to repository root
• Ensure the requirements file exists and is readable
• Check for syntax errors in the requirements file
• Review dependency conflicts in the workflow logs

Issue: Linters report issues that you want to ignore.

Solutions:

• Use linter-specific options to customize behavior:
  • Pylint: pylint-options: '--disable=C0111,W0212'
  • Black: black-options: '--line-length=120'
  • MyPy: mypy-options: '--ignore-missing-imports'
• Create configuration files (.pylintrc, pyproject.toml) in your repository

Issue: Badge commits fail on pull requests from forked repositories.

Solution: This is expected behavior for security reasons. Forks don't have write access. Consider:

• Setting commit-badges: 'false' for PRs from forks
• Using a conditional in your workflow:

  commit-badges: ${{ github.event.pull_request.head.repo.full_name == github.repository && 'true' || 'false' }}

1. Setup Python: Installs specified Python version
2. Install Tools: Installs Pylint, Black, and MyPy
3. Install Requirements: (Optional) Installs dependencies from your requirements file
4. Run Linters: Executes all three linting tools sequentially
5. Generate Badges: Creates SVG badges showing pass/fail status
6. Commit Badges: (Optional) Commits badges back to your repository
7. Generate Summary: Creates detailed GitHub Actions summary with results

✅ Good use cases:

• CI/CD pipelines for Python projects
• Pre-merge checks on pull requests
• Automated code quality enforcement
• Ensuring consistent code style across teams

❌ Not recommended for:

• Local development (use pre-commit hooks instead)
• Projects with custom linting workflows requiring specific tool versions
• Repositories with complex multi-language setups

name: Code Qualityon:
push:
branches: [main]pull_request:
branches: [main]jobs:
lint:
runs-on: ubuntu-latestpermissions:
contents: writesteps:
- uses: actions/checkout@v4
- name: Python Lintinguses: thoughtparametersllc/python-linting@v1with:
python-version: '3.11'requirements-file: 'requirements.txt'

You can customize linter behavior using configuration files in your repository:

• Pylint: .pylintrc or pyproject.toml
• Black: pyproject.toml
• MyPy: mypy.ini or pyproject.toml

Example pyproject.toml:

[tool.black]
line-length = 120target-version = ['py311']
[tool.mypy]
python_version = "3.11"warn_return_any = truewarn_unused_configs = true
[tool.pylint.format]
max-line-length = 120
[tool.pylint.messages_control]
disable = ["C0111", "C0103"]

name: Test and Linton: [push, pull_request]jobs:
test:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5with:
python-version: '3.11'
- run: pip install -r requirements.txt
- run: pytestlint:
runs-on: ubuntu-latestneeds: test # Run after tests passpermissions:
contents: writesteps:
- uses: actions/checkout@v4
- uses: thoughtparametersllc/python-linting@v1with:
requirements-file: 'requirements.txt'

name: Lint Python Codeon: [push]jobs:
lint:
runs-on: ubuntu-latestpermissions:
contents: writesteps:
- uses: actions/checkout@v4# Note: The action runs from repository root regardless of working-directory settings# Specify full paths from root for requirements-file and Python code location
- name: Python Lintinguses: thoughtparametersllc/python-linting@v1with:
requirements-file: './python-service/requirements.txt'

name: PR Linting Checkon: pull_requestjobs:
lint:
runs-on: ubuntu-latestpermissions:
contents: read # Read-only for PR checkssteps:
- uses: actions/checkout@v4
- name: Python Lintinguses: thoughtparametersllc/python-linting@v1with:
commit-badges: 'false'

This repository includes comprehensive GitHub workflows for CI/CD:

• Test Action: Validates all action features across multiple Python versions
• Lint & Test: Ensures code quality with Pylint, Black, MyPy, and Flake8
• Changelog Check: Requires changelog updates for substantive changes
• Release & Marketplace: Automated semantic versioning and tagging

For detailed workflow documentation, see .github/WORKFLOWS.md.

See .github/WORKFLOW_QUICK_START.md for a quick reference guide.

The release workflow supports both automatic semantic versioning and manual version specification:

Automatic Release (when changes are merged to main):

• Automatically detects version bump from CHANGELOG.md
• Creates release with extracted changelog notes
• Updates major version tag (e.g., v1)

Manual Release (for specific versions):

1. Go to Actions → Release and Marketplace → Run workflow
2. Enter version as 1.0.0 or v1.0.0 (for specific version) or major/minor/patch (for semantic bump)
3. The workflow will create the release and update tags

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Update CHANGELOG.md under the [Unreleased] section
5. Ensure all tests pass
6. Submit a pull request

• 📚 Documentation
• 🐛 Report a Bug
• 💡 Request a Feature
• 🔒 Security Policy

This project is licensed under the MIT License - see the LICENSE file for details.

Built with:

• Pylint - Python code analysis
• Black - Python code formatter
• MyPy - Static type checker