CI Pipeline

The plesty-standard-ci GitLab CI component, its four stages, and how to configure it.

Every PLESTY module uses the plesty-standard-ci component from plesty-ci. A single include block configures the full four-stage pipeline.

The full CI architecture — the component-based model, runner images, gate tiers, the module-type matrix, and legacy setups — is documented in CI_ARCHITECTURE.md in the plesty-ci repository. This page covers the practical setup for a module author.

.gitlab-ci.yml

stages:
  - check
  - security
  - deploy
  - release

variables:
  # Required for versioningit: the runner must fetch full Git history and tags.
  GIT_DEPTH: "0"

include:
  - component: $CI_SERVER_FQDN/plesty/plesty-ci/plesty-standard-ci@main
    inputs:
      standard: quantum
      extra_branch: exp
      access_token: $CI_BOT_TOKEN

This is the canonical form — plesty init scaffolds it automatically. Do not add individual component includes (check-compliance, deploy-docs, etc.) — they are legacy and will be migrated. If an existing module still carries the legacy hub-module@exp include (produced by older scaffolds), swap it for plesty-standard-ci@main — the inputs are compatible — so its jobs run on the PLESTY runner image.

Pipeline stages

check
Runs plesty check --standard quantum. All 11 local gates + d1/e1. Fails fast on first gate failure.
security
SAST secret detection scan. Runs on every push. No setup required.
deploy
Sphinx build → push to docs-build branch via CI_BOT_TOKEN. Requires Maintainer token.
release
Build wheel → upload to PyPI. Runs only when a v* tag is pushed. Requires PYPI_TOKEN.

Inputs

Input Required Description
standard yes Compliance standard: pixel, nebula, or quantum
extra_branch yes Additional branch to trigger the deploy stage (besides the default branch)
access_token yes CI/CD variable name for the project access token (always $CI_BOT_TOKEN)

CI_BOT_TOKEN — nothing to set up

CI_BOT_TOKEN is a group-level CI/CD variable inherited by every project in the group, so a new module gets it automatically — there is no per-project token to create. The template references it as access_token: $CI_BOT_TOKEN, and the deploy stage receives it on protected branches.

Do not add a project-level CI_BOT_TOKEN variable. It shadows the group token and expires on its own schedule — the docs-deploy job then 403s while every other gate stays green.

Runner image

The CI runner uses the PLESTY runner image:

registry.gitlab.com/plesty/core/plesty-ci/runner:quantum

This image has Python, uv, and all required tools pre-installed. You do not need to install them in your pipeline.

Checking the pipeline locally

Before pushing, run the full check locally to catch failures before CI sees them:

uv run plesty check --standard quantum

The local check runs the same gates as the CI check stage. If it passes locally, the CI check stage will pass too (barring environment differences, which are rare with the uv lockfile).