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
Secret detection scan. Under quantum, on merge requests, the default branch, exp, maintain/* and tags. No setup required.
deploy
Sphinx build → push to docs-build branch via CI_BOT_TOKEN. A tag deploys that release's docs; never on maintain/*.
release
Build wheel → upload to PyPI. Runs only in a tag pipeline. Authenticates through a PyPI trusted publisher, or with PYPI_TOKEN where one is set.

Inputs

None is required; each has a default.

Input Default Description
standard nebula Compliance standard: pixel, nebula, or quantum
extra_branch — A branch besides the default one whose pushes run the check and deploy jobs — exp for a published module
access_token $CI_JOB_TOKEN The token the deploy job pushes docs-build with — $CI_BOT_TOKEN for a published module
pypi_token — A PyPI token for the release job; leave it unset to publish through a trusted publisher
docs_target_branch docs-build Where the built docs are pushed
python_image the PLESTY runner image The image the jobs run in
check_stage, security_stage, deploy_stage, release_stage check, security, deploy, release Stage names, for a pipeline that names its stages differently
artifact_expire_in — How long job artifacts are kept

CI_BOT_TOKEN

For a module under PLESTY's groups (plesty/hub, plesty/core, plesty/plesty-ai), CI_BOT_TOKEN is a group CI/CD variable: every project inherits it, and there is nothing to set up. Never create a per-project CI_BOT_TOKEN — it would shadow the group's and expire on its own schedule, and the symptom is a deploy-docs job failing with 403 while every other job is green.

The group token has the Maintainer role with read_repository + write_repository scopes. Without Maintainer, 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, with three differences: gate 8 (semantic versioning) is advisory locally and authoritative in CI; the SPDX authorship check in gate 9 runs locally only; and gate 11 (docs build) is skipped in CI branch pipelines, where the deploy job builds the docs instead.