Hub
Docs

Plesty Documentation

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 exactly this, pinned to @main. 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.

@main is the released component; a module pinned to @exp is tracking the CI project's own integration branch and will see template changes before they are released. A few modules still do — move them to @main unless you are deliberately testing a template change.

Pipeline stages

check
Runs plesty check --standard quantum. All 11 numbered local gates plus the lettered gates for this module type. 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)

Setting up CI_BOT_TOKEN

  1. Settings → Access Tokens: create a token named CI_BOT_TOKEN

    • Role: Maintainer
    • Scopes: read_repository + write_repository
    • Expiry: set a reasonable expiry (1 year) and calendar a renewal reminder

  2. Settings → CI/CD → Variables: add the token

    • Key: CI_BOT_TOKEN
    • Value: (paste token value)
    • Flags: Masked + Protected

Without Maintainer role, the deploy step gets 403 on git ls-remote even with read_repository scope.

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).