nabla-hooks

Nabla custom git hooks

This project provides custom Git hooks for code quality validation and is intended to be used by all Nabla products.

Note: This project is in maintenance mode. For new projects, we recommend using commitizen, commitlint, or opencommit with pre-commit hooks.

Features

• Git Branches Check: Validates old stale and already merged branches
• Jenkinsfile Validation: Checks Jenkinsfile syntax and formatting
• JIRA Integration: Optional JIRA ticket validation in commit messages
• Pre-commit Hooks: Integrates with the pre-commit framework

Quick Start

Installation

Install using pip:

pip install nabla-hooks

Or from source:

pip install git+https://github.com/AlbanAndrieu/nabla-hooks.git

Usage

1. Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/AlbanAndrieu/nabla-hooks.git
    rev: v1.0.7
    hooks:
      - id: git-branches-check

2. Install pre-commit hooks:

pre-commit install

3. Run on all files:

pre-commit run --all-files

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• Setting up your development environment with Poetry
• Running tests and code quality checks
• Submitting pull requests
• GitHub workflows and CI/CD

For issues, feature requests, or questions, please use our GitHub issue templates.

Table of contents

// spell-checker:disable

• Features
• Quick Start
  • Installation
  • Usage
• Initialize
  • Requirements
  • Install nabla-hooks as a developer
    • Using virtualenv
  • Install nabla-hooks to use it
    • Using Pip
    • From Source
    • Add .pre-commit-config.yaml in your git project
    • Override global environment variable
    • Local
    • Global
  • Package nabla-hooks as a developer
    • Build a source distribution (a tar archive of all the files needed to build and install the package):
    • Upload a source distribution
  • Test nabla-hooks as a developer
    • shell usage
    • versioneer
    • Test
    • Poetry
    • Pdm
  • Update README.md
  • npm-groovy-lint groovy formatting for Jenkinsfile

// spell-checker:enable

Initialize

Development Setup

Using pipenv with Pipfile:

direnv allow
pyenv install 3.12.10
pyenv local 3.12.10
python -m pipenv install --dev --ignore-pipfile
direnv allow
pre-commit install

Migration from Pipenv to Poetry

If you're migrating from Pipenv:

pip install -U poetry pipenv-poetry-migrate
pipenv-poetry-migrate -f Pipfile -t pyproject.toml --no-use-group-notation

Requirements

Runtime Requirements

This package requires the following to run:

• Python >= 3.9
• pre-commit
• jira (optional, for JIRA integration)

See requirements.txt for the complete list of Python dependencies.

Install nabla-hooks as a developer

Using virtualenv

Install Python 3.12 and virtualenv:

virtualenv --no-site-packages /opt/ansible/env312 -p python3.12
source /opt/ansible/env312/bin/activate

Install Python 3.12 with pyenv:

curl -L https://pyenv.run | bash
echo 'export PATH="~/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
source ~/.bashrc

pyenv install 3.12.10

See pyenv with direnv integration for more details.

pipenv check
python -m pipenv install --dev
python -m pipenv install --dev --ignore-pipfile

Install nabla-hooks to use it

Using Pip

pip install nabla-hooks

From Source

pip install git+https://github.com/AlbanAndrieu/nabla-hooks.git

Add .pre-commit-config.yaml in your git project

1. Create .pre-commit-config.yaml in your git project

Example .pre-commit-config.yaml:

repos:
  - repo: https://github.com/AlbanAndrieu/nabla-hooks.git
    rev: v1.0.7
    hooks:
      - id: git-branches-check
      - id: jira-check  # Validates commit messages contain JIRA tickets
        stages: [commit-msg]

JIRA Check Hook: Validates that commit messages contain JIRA ticket references (e.g., PROJ-123, TEST-456).

Features:

• Pattern matching: [A-Z]{2,10}-[0-9]+ (customizable via --pattern)
• Auto-skips merge, revert, fixup, and squash commits
• No JIRA API access required - simple pattern validation
• User-friendly error messages with examples

Example valid commit messages:

• PROJ-123 Add new feature
• [TEAM-456] Fix critical bug
• ABC-789: Update documentation

Testing locally

repos:
  - repo: local
    hooks:
      - id: git-branches-check
        name: GIT branches check
        description: Check for old stale and already merged branches from the current repo with user friendly messages and colors
        entry: pre_commit_hooks/git-branches-check.sh
        language: script
        types: [shell]
        always_run: true
        verbose: true
        args: [--max=1, --verbose]
    -   id: jira-check
        name: JIRA ticket validation
        entry: hooks/validate_jira.py
        language: python
        stages: [commit-msg]

Test locally:

pre-commit try-repo . git-branches-check --verbose

2. Install pre-commit hooks in your repository

For commit-msg hooks (like JIRA check), also run: pre-commit install --hook-type commit-msg

3. enjoy it

4. Run pre-commit on all files

pre-commit run --all-files

To skip specific hooks:

SKIP=flake8 git commit -am 'Add key'
# Or bypass all hooks
git commit -am 'Add key' --no-verify

Using with OpenCommit (oco)

This project now supports OpenCommit, an AI-powered tool that generates commit messages automatically.

Setup OpenCommit

1. Install OpenCommit globally:

npm install -g opencommit
# or use it with npx
npx opencommit

2. Configure your AI provider (OpenAI, Claude, or local models via Ollama):

oco config set OCO_API_KEY=<your_api_key>
# For local models with Ollama:
# oco config set OCO_AI_PROVIDER=ollama
# oco config set OCO_MODEL=llama3:8b

3. Install as a git hook (optional, if you want AI-generated messages by default):

oco hook set

Using OpenCommit with nabla-hooks

The nabla-hooks prepare-commit-msg hook is now compatible with OpenCommit:

• With OpenCommit hook installed: When you run git commit, OpenCommit will generate a commit message, and nabla-hooks will validate it.
• Manual AI generation: You can use oco command directly to generate and commit:

git add .
oco

• Fallback to commitizen: If no commit message is provided, the hook will fallback to using commitizen for message generation.

The hook intelligently detects existing commit messages (from oco, manual entry, or other tools) and validates them without forcing regeneration.

Override global environment variable

Authentication

See JIRA authentication documentation

Using username/password

export JIRA_USER=aandrieu
export JIRA_PASSWORD=XXX
export JIRA_URL=https://localhost/jira
export JIRA_CERT_PATH=/etc/ssl/certs/NABLA-CA-1.crt
# Or use system CA bundle
export JIRA_CERT_PATH=/etc/ssl/certs/ca-certificates.crt

Using email/token

export JIRA_USER=alban.andrieu@free.fr
export JIRA_PASSWORD=XXX  # Your generated API token
export JIRA_URL=https://localhost/jira

Jenkins authentication

export JENKINS_URL=https://localhost/jenkins/
export JENKINS_USER=aandrieu
export JENKINS_USER_TOKEN=XXX

Git Hooks Templates

See implementing git hooks using Python

Local

First time setup:

# Copy hooks to .git/hooks
cp -r hooks/* .git/hooks/
# Or create symbolic link
rm -Rf ./.git/hooks/ && ln -s ../hooks ./.git/hooks && git checkout repo hooks/

Using auto_prepare_commit_message:

wget -O .git/hooks/prepare-commit-msg https://raw.githubusercontent.com/commitizen-tools/commitizen/master/hooks/prepare-commit-msg.py
chmod +x .git/hooks/prepare-commit-msg
wget -O .git/hooks/post-commit https://raw.githubusercontent.com/commitizen-tools/commitizen/master/hooks/post-commit.py
chmod +x .git/hooks/post-commit

Global

Git uses template directories to initialize new repositories. We have two relevant directories:

• Linux: /usr/share/git-core/templates/
• Windows: C:/Program Files (x86)/Git/share/git-core/templates/ (or C:/Program Files/... on 32-bit)

The hooks are copied from [...]/share/git-core/templates/ directory to .git/hooks/ when initializing a new repository.

Note: If you change the templates directory, the hooks directory must be a subdirectory of the templates directory. Do not set the templates directory to the desired hooks directory.

Setup:

git config --global --get init.templatedir
rm -Rf .git/hooks
git config --global init.templatedir /workspace/users/albandrieu30/nabla-hooks/

Package nabla-hooks as a developer

See setup.cfg documentation

Build a source distribution (a tar archive of all the files needed to build and install the package):

python -m build

Install locally:

pip install .
# Or in editable mode
pip install -e ./

Upload a source distribution

See PyPI API tokens

rm -Rf dist/
pip install setuptools
python3 setup.py sdist bdist_wheel
# Check package
twine check dist/*
nano $HOME/.pypirc
export TWINE_PASSWORD=pypi-
python3 -m twine upload --repository nabla-hooks dist/* --verbose

Published versions:

• Production: nabla-hooks on PyPI
• Test: nabla-hooks on Test PyPI

Test nabla-hooks as a developer

shell usage

Python example:

from hooks import get_msg

match_msg

versioneer

Using versioneer for version management:

versioneer install
# Check version
python setup.py version
python setup.py install

Test

Using tox:

source deactivate
tox --notest
tox -e py  # Run tox using the version of Python in PATH
tox -e py312

Using pytest from the root directory:

pytest --cache-clear --setup-show hooks/tests/pytest_test.py
pytest --cache-clear --setup-show tests/test_package.py

Poetry

Configure PyPI token for publishing

poetry config pypi-token.pypi ${TWINE_PASSWORD} poetry publish --build

Check pyproject.toml for errors

poetry check

Lock dependencies without installing

poetry lock

For more details, see the [CONTRIBUTING.md](.github/CONTRIBUTING.md) guide.

### Pdm

Using [PDM](https://pdm.fming.dev/) for dependency management:

```bash
pdm init
pdm run flake8

GitHub Workflows and CI/CD

This project uses GitHub Actions for continuous integration and deployment. The following workflows are configured:

Available Workflows

1. Python Package (.github/workflows/python.yml)

   • Runs on: Push to master, Pull requests
   • Tests on: Python 3.12 and 3.13 (CI currently runs on 3.12 and 3.13; the project is intended to support Python 3.9+)
   • Steps: Lint (flake8, pylint, bandit), Test (pytest, tox)
   • Badge:

2. CodeQL Analysis (.github/workflows/codeql.yml)

   • Security scanning for code vulnerabilities
   • Runs on: Push and Pull requests

3. Linter (.github/workflows/linter.yml)

   • Comprehensive linting across the project
   • Uses MegaLinter for multiple file types

4. Release (.github/workflows/release.yml)

   • Automated release creation and publishing

5. Tests (.github/workflows/tests.yml)

   • Dedicated test workflow

Workflow Requirements

All pull requests must pass:

• ✅ Linting (flake8, pylint, bandit)
• ✅ Tests (pytest with >30% coverage)
• ✅ Code quality checks (SonarCloud)
• ✅ Security scanning (CodeQL)

Local CI Simulation

Before pushing, run the same checks locally:

# Activate poetry environment
poetry shell

# Run linters
poetry run flake8 hooks tests
poetry run pylint hooks
poetry run bandit -r hooks

# Run tests
poetry run pytest --cov=hooks --cov-fail-under=30

# Run pre-commit hooks
poetry run pre-commit run --all-files

For more details, see CONTRIBUTING.md.

Update README.md

Using markdown-toc to update the table of contents:

npm install --save markdown-toc
markdown-toc README.md -i
markdown-toc CHANGELOG.md -i

With pre-commit hooks:

pre-commit install
git add README.md
pre-commit run markdown-toc

Check markdown syntax with remark-lint:

npm run lint-md

npm-groovy-lint groovy formatting for Jenkinsfile

Groovy linting and formatting for Jenkinsfile. Tested with Node.js 12 and 16 on Ubuntu 20 and 21 (not working with Node.js 11 and 14).

npm install -g npm-groovy-lint@8.2.0
npm-groovy-lint --format
ll .groovylintrc.json

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commit messages
4. Add tests if applicable
5. Run pre-commit hooks and tests locally
6. Submit a pull request

License

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

Support

• Issues
• Gitter Chat

Acknowledgments

This project uses several open-source tools and libraries. See requirements.txt for the complete list.