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.

.gitlab-ci.yml

stages:
  - check
  - security
  - deploy
  - release

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

This is the canonical form. Do not add individual component includes (check-compliance, deploy-docs, etc.) — they are legacy and will be migrated.

Pipeline stages

check
Runs plesty check --standard quantum. All 11 local gates + d1. 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).