Pre-Commit Odoo Apps: Step-by-Step Automation Tutorial

pre-commit Odoo apps ensure that your code meets style and quality standards before you commit. First, we guide you through setting up pre-commit for Odoo modules. Next, we explain how to integrate OCA hooks such as pylint-odoo and flake8-odoo. Moreover, this pre-commit Odoo apps tutorial uses clear examples, active voice, and transition words to keep instructions sharp. Finally, you will master pre-commit Odoo apps hooks to save time and avoid errors. For more details on pre-commit, visit the official documentation: https://pre-commit.com/.

source : https://github.com/odooerpdevelopers/mis-addons-public

Prerequisites for pre-commit Odoo apps

Before you start automating checks in your Odoo code, you need a solid base. Therefore, we list all requirements clearly.

Local Odoo development environment

You must install a compatible Odoo version (e.g., Odoo 15 or 16). Then, clone or download your company’s Odoo project or the OCA add‑ons repository. Next, ensure you can run Odoo locally with a simple ./odoo-bin -c config.conf command. Consequently, you prepare your codebase for Git hooks.

Python and virtual environment

Install Python 3.8 or later. Meanwhile, create a virtual environment to isolate dependencies:

python3 -m venv .venv
source .venv/bin/activate

Then, upgrade pip and setuptools:

pip install --upgrade pip setuptools

Finally, you avoid conflicts and lock versions per project.

Git and GitHub (or GitLab) access

You must install Git and configure your user details:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

After that, clone your repository:

git clone https://github.com/your-org/your-odoo-repo.git
cd your-odoo-repo

Thus, you set up code hosting for pre-commit integration.

Familiarity with YAML syntax

pre-commit uses a YAML file for configuration. Therefore, you should know basic YAML rules: two‑space indentation, key–value pairs, lists. In the next section, you will see detailed examples.

Installing pre-commit for Odoo modules

You install pre-commit as a development dependency. Then, you register Git hooks that automatically run checks on every commit.

pip install pre-commit

First, install pre-commit in your virtual environment:

pip install pre-commit

Next, verify installation:

pre-commit --version
# Example output: pre-commit 2.20.0

As a result, you confirm that the tool is ready to use.

Enable hooks in your repository

Within your project root, type:

pre-commit install

Then, Git generates a .git/hooks/pre-commit script that runs before each commit. Consequently, you ensure that code quality checks fire automatically.

Configuring pre-commit for Odoo projects

Your central configuration file lives at the repository root. You name it .pre-commit-config.yaml. In this file, you declare each hook, its source repo, and its arguments.

Basic .pre-commit-config.yaml structure

Create .pre-commit-config.yaml and add:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer

  - repo: https://github.com/OCA/pylint-odoo
    rev: 2.13.0
    hooks:
      - id: pylint-odoo
        args: ["--rcfile=pylintrc"]

  - repo: https://github.com/OCA/flake8-odoo
    rev: 15.0.0
    hooks:
      - id: flake8-odoo
        additional_dependencies: ["flake8>=3.9.2"]

Let us explain each part:

1. repos: You list external repositories that provide hooks.
2. repo: pre-commit-hooks: You include basic pre-commit tools (whitespace, file fixes).
3. repo: OCA/pylint-odoo: You integrate OCA’s Pylint plugin for Odoo module checks.
4. rev: You pin to a specific release for stability.
5. hooks: Under each repo, you declare one or more hook IDs.
6. args and additional_dependencies: You pass custom options and any extra Python packages needed.

Detailed hook configuration

You can tune each hook. For example, to skip certain files or run only on Python code, you adjust patterns:

      - id: flake8-odoo
        files: \.py$
        exclude: tests/fixtures/
        args: ["--config", "flake8.cfg"]

Here, you restrict flake8-odoo to .py files and exclude fixture data. Moreover, you load custom settings from flake8.cfg.

Integrating OCA plugins with pre-commit

The OCA ecosystem offers specialized hooks beyond generic checks. Consequently, you strengthen module quality and adhere to OCA guidelines.

pylint-odoo Git hook setup

pylint-odoo enforces Odoo manifest formats, model naming, translations, and documentation. You already added it above. Now, create a pylintrc file in your repo:

[MASTER]
load-plugins=pylint_odoo

[MESSAGES CONTROL]
disable=C0114,C0115,C0116

[ODOO]
# Adapt this to your Odoo version
version=16.0

Then, explain:

• load-plugins: You load the pylint_odoo plugin.
• disable: You silence certain messages (e.g., missing docstrings).
• ODOO section: You set your target Odoo version.

After that, every pylint-odoo run will check modules against OCA standards.

flake8-odoo hook configuration

flake8-odoo targets code style, complexity, and Odoo‑specific patterns. You include it in your YAML above. Next, create flake8.cfg:

[flake8]
max-line-length = 100
exclude = .git,__pycache__,env
select = C,E,F,W,B,B950
ignore = F403,F405

Then, discuss:

• max-line-length: You choose 100 to match Odoo conventions.
• exclude: You skip virtualenv and cache.
• select: You pick groups of errors for compliance.
• ignore: You silence false positives.

Thus, you ensure consistent style across your pre-commit Odoo apps.

Local hooks for custom checks

Sometimes you need project‑specific scripts. You add a local section:

  - repo: local
    hooks:
      - id: check-manifest
        name: Manifest formatting
        entry: bash scripts/check_manifest.sh
        language: system
        pass_filenames: false

Then, you explain:

• repo: local: You define inline hooks.
• entry: You call your shell script for extra checks.
• pass_filenames: You disable passing file lists if your script handles everything.

Therefore, you can extend pre-commit with any tool.

Automating pre-commit checks in CI pipelines

Running pre-commit hooks locally helps catch issues early. However, you also automate checks in your continuous integration (CI) workflows on GitHub or GitLab.

GitHub Actions workflow example

Create .github/workflows/pre-commit.yml:

name: CI / pre-commit checks
on:
  pull_request:
    paths:
      - '**.py'
      - '.pre-commit-config.yaml'
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          pip install pre-commit
      - name: Run pre-commit hooks
        run: |
          pre-commit run --all-files

Let us break it down:

1. on: pull_request: You trigger on PRs affecting Python code or the config file.
2. actions/setup-python: You choose a Python runner.
3. Install dependencies: You prepare the virtual environment and install pre-commit.
4. Run pre-commit hooks: You enforce all configured hooks across the codebase.

Consequently, CI blocks merges if any pre-commit checks fail.

GitLab CI integration

For GitLab, add to .gitlab-ci.yml:

precommit:
  image: python:3.9
  before_script:
    - pip install pre-commit
  script:
    - pre-commit run --all-files
  only:
    - merge_requests

Then, you ensure that merge requests run your pre-commit Odoo apps checks automatically.

Best practices for Odoo pre-commit integration

After you set up basic hooks, follow these tips to boost maintainability and performance.

Pin hook versions

Always pin to a specific rev: in your YAML. Furthermore, you schedule updates by reviewing new releases. This approach prevents unexpected breakages.

Use YAML anchors and aliases

You can reduce repetition in .pre-commit-config.yaml:

defaults: &defaults
  files: \.py$
  exclude: tests/data/

repos:
  - repo: https://github.com/OCA/pylint-odoo
    rev: 2.13.0
    hooks:
      - id: pylint-odoo
        <<: *defaults
  - repo: https://github.com/OCA/flake8-odoo
    rev: 15.0.0
    hooks:
      - id: flake8-odoo
        <<: *defaults

Here, you define shared settings under defaults and reuse them via <<: *defaults.

Limit hook execution scope

You can speed up hooks by targeting only staged files:

pre-commit run --hook-stage commit

Alternatively, use --files and list only changed files in CI jobs.

Document your setup

Include a CONTRIBUTING.md file that explains how new contributors must install and run pre-commit. As a result, you on‑board team members faster and enforce consistency.

Troubleshooting common issues

Even with a solid setup, you may face errors. Here are solutions to frequent pitfalls.

Hook installation fails

If pre-commit install throws permission errors, check file permissions under .git/hooks. Then, run:

chmod +x .git/hooks/pre-commit

Moreover, ensure that your Git version supports hooks.

Conflicting dependency errors

Sometimes two hooks require different versions of the same package. In that case, isolate hooks by using Docker or separate virtual environments. Alternatively, use language: python3 and specify additional_dependencies per hook.

Slow hook execution

If hooks run too slowly, you can:

• Use the --hook-type option to run only specific stages.
• Cache virtual environments in CI.
• Run lightweight hooks locally (e.g., whitespace fixes) and defer heavy ones to CI.

Skipping hooks temporarily

On rare occasions, you may want to bypass hooks:

git commit --no-verify -m "Temporary skip"

However, avoid habitual skipping. Instead, fix the underlying issue.

Conclusion

pre-commit Odoo apps integration brings automated code quality checks directly into your development workflow. By combining pre-commit with OCA plugins, you enforce Odoo-specific standards, prevent regressions, and speed up code review cycles. Moreover, integrating hooks into CI pipelines guarantees consistency across all branches. Finally, you maintain a clean codebase, improve team collaboration, and deliver reliable Odoo apps. Start automating today and enjoy smoother releases!