Mypy GitLab Code Quality

Warnings

• gotcha While `mypy-gitlab-code-quality` supports both JSON and plain text output from `mypy`, JSON output is strongly recommended for more robust and consistent parsing. Relying on plain text output might lead to unexpected behavior if `mypy`'s output format changes in future versions.
  Fix: Always configure `mypy` to output JSON using the `--output=json` flag when generating input for `mypy-gitlab-code-quality`.
• gotcha GitLab Code Quality reports expect file paths to be relative to the project root. If the `mypy` output contains absolute paths or paths that are not correctly relative to the project's root directory, code quality issues might not be displayed or linked correctly in GitLab merge requests.
  Fix: Ensure `mypy` is run from the project's root directory or configure `mypy` to output relative paths. Verify the paths in the generated `codequality.json`.
• gotcha The `mypy-gitlab-code-quality` script outputs the generated GitLab Code Quality JSON directly to `STDOUT`. For GitLab CI to properly collect and display this as a code quality artifact, the `STDOUT` must be redirected to a file (e.g., `codequality.json`). Failure to redirect will result in no report being generated or displayed by GitLab.
  Fix: In your CI/CD script, ensure you redirect the output: `mypy-gitlab-code-quality < mypy-out.json > codequality.json`.
• gotcha GitLab recommends setting `allow_failure: true` for Code Quality jobs. This practice prevents the entire CI/CD pipeline from failing due to detected quality issues, allowing other pipeline stages (like tests) to complete. It also ensures a full overview of quality findings is available without blocking merge requests unnecessarily.
  Fix: Add `allow_failure: true` to your `codequality` job definition in your `.gitlab-ci.yml` file.
• deprecated The official GitLab Code Quality component based on CodeClimate scanning is deprecated and planned for removal in GitLab version 19.0 (around May 2026). While `mypy-gitlab-code-quality` is used by a separate, community-supported GitLab component (`codequality-os-scanners-integration`) for conversion to CodeClimate format, users should be aware of the broader deprecation of the built-in CodeClimate engine.
  Fix: Monitor GitLab documentation for updates on Code Quality integration, especially with GitLab 19.0 and beyond, to understand any necessary adjustments to the Code Climate format or integration methods.
• gotcha The functionality of `mypy-gitlab-code-quality` depends on the output format of `mypy`. Major versions of `mypy` may introduce breaking changes to their output, drop support for older Python versions (e.g., Mypy 1.20 dropped Python 3.9 support), or change default behaviors (e.g., `--local-partial-types` in Mypy 2.0). Ensure compatibility between your installed `mypy` version and `mypy-gitlab-code-quality`, and your project's Python version.
  Fix: Regularly check the release notes for both `mypy` and `mypy-gitlab-code-quality` for compatibility information. It is advisable to pin specific versions of `mypy` and `mypy-gitlab-code-quality` in your CI/CD environment to prevent unexpected breaks.

Install

• pip install mypy-gitlab-code-quality Install with pip

Imports

• mypy-gitlab-code-quality

  This library is primarily used as a command-line tool, typically invoked directly in shell scripts (e.g., in GitLab CI) rather than imported as a Python module for its core functionality.

  The common usage pattern involves piping Mypy's output to the `mypy-gitlab-code-quality` executable.

Quickstart

This example demonstrates how to integrate `mypy-gitlab-code-quality` into a GitLab CI/CD pipeline. It installs `mypy` and `mypy-gitlab-code-quality`, runs `mypy` on `program.py` (ensuring JSON output), then pipes that output to `mypy-gitlab-code-quality` to generate `codequality.json`. This JSON file is declared as a `codequality` artifact for GitLab to parse and display in merge requests. The `allow_failure: true` setting is recommended for code quality jobs.

image: python:alpine

codequality:
  script:
    - pip install mypy mypy-gitlab-code-quality
    # Run mypy and capture its JSON output to a temporary file
    - mypy program.py --output=json > mypy-out.json || true # '|| true' prevents job failure if mypy finds errors
    # Process mypy output into GitLab Code Quality format and redirect to 'codequality.json'
    - mypy-gitlab-code-quality < mypy-out.json > codequality.json
  artifacts:
    when: always
    reports:
      codequality: codequality.json
  allow_failure: true # Recommended for code quality jobs to not block pipelines