Tutorial: Build and sign Python packages with GitLab CI/CD

This tutorial shows you how to implement a secure pipeline for Python packages. The pipeline includes stages that cryptographically sign and verify Python packages using GitLab CI/CD and Sigstore Cosign.

By the end, you’ll learn how to:

Build and sign Python packages using GitLab CI/CD.
Store and manage package signatures using the generic package registry.
Verify package signatures as an end user.

What are the benefits of package signing?

Package signing provides several crucial security benefits:

Authenticity: Users can verify that packages come from trusted sources.
Data integrity: If a package is tampered with during distribution, it will be detected.
Non-repudiation: The origin of a package can be cryptographically proven.
Supply chain security: Package signing protects against supply chain attacks and compromised repositories.

Before you begin

To complete this tutorial, you need:

A GitLab account and test project.
Basic familiarity with Python packaging, GitLab CI/CD, and package registry concepts.

Steps

Here’s an overview of what you’re going to do:

Set up a Python project

First, create a test project. Add a pyproject.toml file in your project root:

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "<my_package>"  # Will be dynamically replaced by CI/CD pipeline
version = "<1.0.0>"    # Will be dynamically replaced by CI/CD pipeline
description = "<Your package description>"
readme = "README.md"
requires-python = ">=3.7"
authors = [
    {name = "<Your Name>", email = "<your.email@example.com>"},
]

[project.urls]
"Homepage" = "<https://gitlab.com/my_package>"  # Will be replaced with actual project URL

Make sure you replace Your Name and your.email@example.com with your own personal details.

When you finish building your CI/CD pipeline in the following steps, the pipeline automatically:

Replaces my_package with a normalized version of your project name.
Changes the version to match the pipeline version.
Changes the Homepage URL to match your GitLab project URL.

Add base configuration

In your project root, add a .gitlab-ci.yml file. Add the following configuration:

variables:
  # Base Python version for all jobs
  PYTHON_VERSION: '3.10'
  # Package names and versions
  PACKAGE_NAME: ${CI_PROJECT_NAME}
  PACKAGE_VERSION: "1.0.0"  # Use semantic versioning
  # Sigstore service URLs
  FULCIO_URL: 'https://fulcio.sigstore.dev'
  REKOR_URL: 'https://rekor.sigstore.dev'
  # Identity for Sigstore verification
  CERTIFICATE_IDENTITY: 'https://gitlab.com/${CI_PROJECT_PATH}//.gitlab-ci.yml@refs/heads/${CI_DEFAULT_BRANCH}'
  CERTIFICATE_OIDC_ISSUER: 'https://gitlab.com'
  # Pip cache directory for faster builds
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
  # Auto-accept prompts from Cosign
  COSIGN_YES: "true"
  # Base URL for generic package registry
  GENERIC_PACKAGE_BASE_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${PACKAGE_NAME}/${PACKAGE_VERSION}"

default:
  before_script:
    # Normalize package name once at the start of any job
    - export NORMALIZED_NAME=$(echo "${CI_PROJECT_NAME}" | tr '-' '_')

# Template for Python-based jobs
.python-job:
  image: python:${PYTHON_VERSION}
  before_script:
    # First normalize package name
    - export NORMALIZED_NAME=$(echo "${CI_PROJECT_NAME}" | tr '-' '_')
    # Then install Python dependencies
    - pip install --upgrade pip
    - pip install build twine setuptools wheel
  cache:
    paths:
      - ${PIP_CACHE_DIR}

# Template for Python + Cosign jobs
.python+cosign-job:
  extends: .python-job
  before_script:
    # First normalize package name
    - export NORMALIZED_NAME=$(echo "${CI_PROJECT_NAME}" | tr '-' '_')
    # Then install dependencies
    - apt-get update && apt-get install -y curl wget
    - wget -O cosign https://github.com/sigstore/cosign/releases/download/v2.2.3/cosign-linux-amd64
    - chmod +x cosign && mv cosign /usr/local/bin/
    - export COSIGN_EXPERIMENTAL=1
    - pip install --upgrade pip
    - pip install build twine setuptools wheel
stages:
  - build
  - sign
  - verify
  - publish
  - publish_signatures
  - consumer_verification

This base configuration:

Instructs the pipeline to use Python 3.10 as the base image for consistency
Sets up two reusable templates: .python-job for basic Python operations and .python+cosign-job for signing operations
Implements pip caching to speed up builds
Normalizes package names by converting hyphens to underscores for Python compatibility
Defines all key variables at the pipeline level for easy management