GitLab CI template for Python

This project implements a GitLab CI/CD template to build, test and analyse your Python projects.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python@7.9.0
    # 2: set/override component inputs
    inputs:
      image: registry.hub.docker.com/library/python:3.12-slim
      pytest-enabled: true

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/python'
    ref: '7.9.0'
    file: '/templates/gitlab-ci-python.yml'

variables:
  # 2: set/override template variables
  PYTHON_IMAGE: registry.hub.docker.com/library/python:3.12-slim
  PYTEST_ENABLED: "true"

Global configuration

The Python template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
image / PYTHON_IMAGE	The Docker image used to run Python ⚠️ set the version required by your project	registry.hub.docker.com/library/python:3-slim
project-dir / PYTHON_PROJECT_DIR	Python project root directory	.
build-system / PYTHON_BUILD_SYSTEM	Python build-system to use to install dependencies, build and package the project (see below)	auto (auto-detect)
PIP_INDEX_URL	Python repository url	none
PIP_EXTRA_INDEX_URL	Extra Python repository url	none
pip-opts / PIP_OPTS	pip extra options	none
extra-deps / PYTHON_EXTRA_DEPS	Python extra sets of dependencies to install For Setuptools or Poetry only	none
reqs-file / PYTHON_REQS_FILE	Main requirements file (relative to $PYTHON_PROJECT_DIR) For Requirements Files build-system only	requirements.txt
extra-reqs-files / PYTHON_EXTRA_REQS_FILES	Extra dev requirements file(s) to install (relative to $PYTHON_PROJECT_DIR)	requirements-dev.txt

The cache policy also makes the necessary to manage pip cache (not to download Python dependencies over and over again).

Multi build-system support

The Python template supports the most popular dependency management & build systems.

By default it tries to auto-detect the build system used by the project (based on the presence of pyproject.toml and/or setup.py and/or requirements.txt), but the build system might also be set explicitly using the $PYTHON_BUILD_SYSTEM variable:

⚠️ You can explicitly set the build tool version by setting $PYTHON_BUILD_SYSTEM variable including a version identification. For example PYTHON_BUILD_SYSTEM="poetry==1.1.15"

Jobs

py-package job

This job allows building your Python project distribution packages.

It is bound to the build stage, it is disabled by default and can be enabled by setting $PYTHON_PACKAGE_ENABLED to true.

Lint jobs

py-lint job

This job is disabled by default and performs code analysis based on pylint Python lib. It is activated by setting $PYLINT_ENABLED to true.

It is bound to the build stage, and uses the following variables:

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Test jobs

The Python template features four alternative test jobs:

• py-unittest that performs tests based on unittest Python lib,
• or py-pytest that performs tests based on pytest Python lib,
• or py-nosetest that performs tests based on nose Python lib,
• or py-compile that performs byte code generation to check syntax if not tests are available.

py-unittest job

This job is disabled by default and performs tests based on unittest Python lib. It is activated by setting $UNITTEST_ENABLED to true.

In order to produce JUnit test reports, the tests are executed with the xmlrunner module.

It is bound to the build stage, and uses the following variables:

ℹ️ use a .coveragerc file at the root of your Python project to control the coverage settings.

Example:

[run]
# enables branch coverage
branch = True
# list of directories/packages to cover
source =
    module_1
    module_2

In addition to a textual report in the console, this job produces the following reports, kept for one day:

py-pytest job

This job is disabled by default and performs tests based on pytest Python lib. It is activated by setting $PYTEST_ENABLED to true.

It is bound to the build stage, and uses the following variables:

ℹ️ use a .coveragerc file at the root of your Python project to control the coverage settings.

Example:

[run]
# enables branch coverage
branch = True
# list of directories/packages to cover
source =
    module_1
    module_2

In addition to a textual report in the console, this job produces the following reports, kept for one day:

py-nosetests job

This job is disabled by default and performs tests based on nose Python lib. It is activated by setting $NOSETESTS_ENABLED to true.

It is bound to the build stage, and uses the following variables:

By default coverage will be run on all the project directories. You can restrict it to your packages by setting the $NOSE_COVER_PACKAGE variable. More info

ℹ️ use a .coveragerc file at the root of your Python project to control the coverage settings.

In addition to a textual report in the console, this job produces the following reports, kept for one day:

py-compile job

This job is a fallback if no unit test has been set up ($UNITTEST_ENABLED and $PYTEST_ENABLED and $NOSETEST_ENABLED are not set), and performs a compileall.

It is bound to the build stage, and uses the following variables:

py-bandit job (SAST)

This job is disabled by default and performs a Bandit analysis.

It is bound to the test stage, and uses the following variables:

In addition to a textual report in the console, this job produces the following reports, kept for one day and only available for download by users with the Developer role or higher:

py-trivy job (dependency check)

This job performs a dependency check analysis using Trivy. ⚠️ This job is now enabled by default since version 7.0.0

It is bound to the test stage, and uses the following variables:

Other Trivy parameters shall be configured using Trivy environment variables. Examples:

• TRIVY_SEVERITY: severities of security issues to be displayed (comma separated values: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL)
• TRIVY_SERVER: server address (enables client/server mode)
• TRIVY_DB_REPOSITORY: OCI repository to retrieve Trivy Database from
• ...

⚠️ if you're using Trivy in multiple templates with different parameter values (ex: different TRIVY_SEVERITY threshold with Python and - says - Docker templates), then it is recommanded to pass the configuration as CLI options using the trivy-args input / PYTHON_TRIVY_ARGS variable.

In addition to a textual report in the console, this job produces the following reports, kept for one day and only available for download by users with the Developer role or higher:

py-sbom job

This job generates a SBOM file listing all dependencies using syft.

It is bound to the test stage, and uses the following variables:

In addition to logs in the console, this job produces the following reports, kept for one week:

py-black job

This job disabled by default and runs black on the repo. It is bound to the build stage.

py-isort job

This job disabled by default and runs isort on the repo. It is bound to the build stage.

py-ruff job

This job disabled by default and runs Ruff on the repo. It is bound to the build stage.

⚠️ Ruff can replace isort, Bandit, Pylint and much more. More info.

In addition to logs in the console, this job produces the following reports, kept for one week:

py-ruff-format job

This job disabled by default and runs Ruff on the repo. It is bound to the build stage.

⚠️ Ruff can replace Black and much more. More info.

py-mypy job

This job is disabled by default and performs code analysis based on mypy. It is activated by setting $MYPY_ENABLED to true.

It is bound to the build stage, and uses the following variables:

In addition to a textual report in the console, this job produces the following reports, kept for one day:

SonarQube analysis

If you're using the SonarQube template to analyse your Python code, here is a sample sonar-project.properties file:

# see: https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/python-test-coverage/
# set your source directory(ies) here (relative to the sonar-project.properties file)
sonar.sources=.
# exclude unwanted directories and files from being analysed
sonar.exclusions=**/test_*.py

# set your tests directory(ies) here (relative to the sonar-project.properties file)
sonar.tests=.
sonar.test.inclusions=**/test_*.py

# tests report: xUnit format
sonar.python.xunit.reportPath=reports/TEST-*.xml
# coverage report: Cobertura format
sonar.python.coverage.reportPaths=reports/py-coverage.cobertura.xml
# pylint: parseable format (if enabled)
sonar.python.pylint.reportPaths=reports/py-lint.parseable.txt
# Bandit: CSV format (if enabled)
sonar.python.bandit.reportPaths=reports/py-bandit.bandit.csv
# Ruff: JSON format (if enabled)
sonar.python.ruff.reportPaths=reports/py-ruff.native.json
# mypy: JSON format (if enabled)
sonar.python.mypy.reportPaths=reports/py-mypy.console.txt

More info:

• Python language support
• test coverage & test execution parameters
• external analyzer reports

py-release job

This job is disabled by default and allows to perform a complete release of your Python code:

1. increase the Python project version,
2. Git commit changes and create a Git tag with the new version number,
3. build the Python packages,
4. publish the built packages to a PyPI compatible repository (GitLab packages by default).

The Python template supports three packaging systems:

• Poetry: uses Poetry-specific version, build and publish commands.
• uv: uses uv as version management, build as package builder and publish to publish.
• Setuptools: uses bump-my-version as version management, build as package builder and Twine to publish.

The release job is bound to the publish stage, appears only on production and integration branches and uses the following variables:

When py-release job is enabled, py-publish job is automatically enabled too.

py-publish job

This job is disabled by default and allow to publish the built packages to a PyPI compatible repository (GitLab packages by default.

The Python template supports three packaging systems:

• Poetry: uses Poetry-specific version, build and publish commands.
• uv: uses uv as version management, build as package builder and publish to publish.
• Setuptools: uses bump-my-version as version management, build as package builder and Twine to publish.

The publish job is bound to the publish stage, is executed on a Git tag matching semantic versioning pattern and uses the following variables:

Setuptools tip

If you're using a Setuptools configuration, then you will have to write a .bumpversion.toml or pyproject.toml file.

Example of .bumpversion.toml file:

[tool.bumpversion]
current_version = "0.0.0"

Example of pyproject.toml file:

[project]
name = "project-name"

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[tool.bumpversion]
current_version = "0.0.0"

[[tool.bumpversion.files]]
filename = "project-name/__init__.py"

semantic-release integration

If you activate the semantic-release-info job from the semantic-release template, the py-release job will rely on the generated next version info. Thus, a release will be performed only if a next semantic release is present.

You should disable the semantic-release job (as it's the py-release job that will perform the release and so we only need the semantic-release-info job) by setting SEMREL_RELEASE_DISABLED to true.

Finally, the semantic-release integration can be disabled with the PYTHON_SEMREL_RELEASE_DISABLED variable.

Git authentication

A Python release involves some Git push operations.

You can either use a SSH key or user/password credentials.

Using a SSH key

We recommend you to use a project deploy key with write access to your project.

The key should not have a passphrase (see how to generate a new SSH key pair).

Specify 🔒 $GIT_PRIVATE_KEY as secret project variable with the private part of the deploy key.

-----BEGIN 0PENSSH PRIVATE KEY-----
blablabla
-----END OPENSSH PRIVATE KEY-----

The template handles both classic variable and file variable.

Using user/password credentials

Simply specify 🔒 $GIT_USERNAME and 🔒 $GIT_PASSWORD as secret project variables.

Note that the password should be an access token (preferably a project or group access token) with write_repository scope and Maintainer role.

Pip repositories

When depending on Python packages published in GitLab's packages registry, it could be useful to configure a group level Package. But such repository will require an authenticated access.

To do so, simply set the PIP_INDEX_URL and use the CI job token.

variables:
  PIP_INDEX_URL: "${CI_SERVER_PROTOCOL}://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}:${CI_SERVER_PORT}/api/v4/groups/<group-id>/-/packages/pypi/simple"

In a corporate environment, you can be faced to two repositories: the corporate proxy-cache and the project repository.

Simply use both PIP_INDEX_URL and PIP_EXTRA_INDEX_URL.

variables:
  PIP_INDEX_URL: "https://cache.corp/repository/pypi/simple"
  PIP_EXTRA_INDEX_URL: "${CI_SERVER_PROTOCOL}://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}:${CI_SERVER_PORT}/api/v4/groups/<group-id>/-/packages/pypi/simple"

Variants

The Python template can be used in conjunction with template variants to cover specific cases.

Vault variant

This variant allows delegating your secrets management to a Vault server.

Configuration

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

By default, the variant will authentifacte using a JWT ID token. To use AppRole instead the VAULT_ROLE_ID and VAULT_SECRET_ID should be defined as secret project variables.

Usage

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Example

include:
  # main component
  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python@7.9.0
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python-vault@7.9.0
    inputs:
      vault-base-url: "https://vault.acme.host/v1"
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"

variables:
    # Secrets managed by Vault
    GIT_PASSWORD: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/git/semantic-release?field=group-access-token"
    GIT_PRIVATE_KEY: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/git/semantic-release?field=private-key"
    PYTHON_REPOSITORY_PASSWORD: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/pip-repo/repository?field=password"

Google Cloud variant

This variant allows to use Python Google Clients. The variant follow the recommendation Authenticate for using client libraries with ADC

Detailed article on internal OIDC impersonated with Workload Identify Federation

List of requirements before using this variant for use Python Google Clients:

1. You must have a Workload Identity Federation Pool,
2. You must have a Service Account with enough permissions to run your python job.
3. Optional, you can define GOOGLE_CLOUD_PROJECT in template variable to define the default Google project

Configuration

The variant requires the additional configuration parameters:

Example

include:
  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python@7.9.0
    # 2: set/override component inputs
    inputs:
      image: registry.hub.docker.com/library/python:3.12-slim
      pytest-enabled: true

  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python-gcp@7.9.0
    inputs:
      # common OIDC config for non-prod envs
      gcp-oidc-provider: "projects/<gcp_nonprod_proj_id>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>"
      gcp-oidc-account: "<name>@$<gcp_nonprod_proj_id>.iam.gserviceaccount.com"

AWS CodeArtifact variant

This variant allows to use PyPi packages from AWS CodeArtifact. The variant follow the recommendation Authenticate for using client libraries

It authenticates with AWS CodeArtifact, retrieves and sets the following environment variable:

• CODEARTIFACT_AUTH_TOKEN - the AWS CodeArtifact authentication token
• CODEARTIFACT_REPOSITORY_ENDPOINT - the AWS CodeArtifact repository endpoint
• CODEARTIFACT_URL - Formatted URL for the AWS CodeArtifact repository

Most importantly, the variant sets the pip global.index-url to the CodeArtifact url.

The variant supports two authentication methods:

1. federated authentication using OpenID Connect (recommended method),
2. or basic authentication with AWS access key ID & secret access key.

⚠️ when using this variant, you must have created the CodeArtifact repository.

Configuration

The variant requires the additional configuration parameters:

OIDC authentication config

This is the recommended authentication method. In order to use it, first carefuly follow GitLab's documentation, then set the required configuration.

Basic authentication config

Example

include:
  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python@7.9.0
    # 2: set/override component inputs
    inputs:
      image: registry.hub.docker.com/library/python:3.12-slim
      pytest-enabled: true

  - component: $CI_SERVER_FQDN/to-be-continuous/python/gitlab-ci-python-aws-codeartifact@7.9.0
    inputs:
      aws-region: "us-east-1"
      aws-codeartifact-domain: "acme"
      aws-codeartifact-domain-owner: "123456789012"
      aws-codeartifact-repository: "my-repo"
      # common OIDC config for non-prod envs
      aws-oidc-role-arn: "arn:aws:iam::123456789012:role/gitlab-ci"