GitLab CI Integration

Overview 

cikit can run project commands inside GitLab CI without requiring a separate command implementation.

When GitLab CI is active, cikit selects GitLabProvider automatically and maps GitLab pipeline metadata to the common cikit provider interface.

This guide covers only GitLab-specific integration:

provider detection and metadata
GitLab log sections
GitLab job artifacts
GitLab Code Quality reports
GitLab CI/CD variables for remote cikit data
GitLab Pages deployment

General command structure, artifact handling, local workflows, and Sphinx internals are documented separately.

Provider Detection 

GitLab CI is detected through:

GITLAB_CI=true

cikit then uses GitLabProvider.

The provider maps GitLab project and pipeline identity to the common cikit interface:

Provider property	GitLab variable	Meaning
`provider_scope`	`CI_PROJECT_NAMESPACE`	Project namespace.
`provider_project`	`CI_PROJECT_NAME`	Project name.
`pipeline_id`	`CI_PIPELINE_ID`	Pipeline identifier.

Git revision metadata is likewise obtained from GitLab CI variables.

Project commands should normally access these values through the cikit environment instead of reading GitLab variables directly.

For the complete mapping, see Providers.

GitLab Log Sections 

CiSection uses the active provider to render provider-specific log groups.

Under GitLab CI, cikit emits GitLab section markers so command steps appear as grouped sections in the job log.

Project commands therefore do not need GitLab-specific logging code for normal section handling.

See CI Commands for CiSection and command status behavior.

Job Artifacts 

cikit stores persistent generated output below PUBLIC_DIR.

With the default configuration this is:

public/

A GitLab job can publish the complete cikit output with:

artifacts:
  when: always
  paths:
    - public

Publishing the complete directory keeps the GitLab configuration independent of the internal cikit artifact layout.

If PUBLIC_DIR is customized, the GitLab artifact path must be adjusted accordingly.

For the cikit artifact model, see Artifacts.

GitLab Code Quality 

Projects may generate GitLab Code Quality reports from lint commands.

The cikit Ruff and Pylint integrations can produce provider-specific Code Quality JSON files that are then registered in .gitlab-ci.yml.

Example for Ruff:

artifacts:
  reports:
    codequality:
      - public/artifacts/ruff-codequality.json

Example for Pylint:

artifacts:
  reports:
    codequality:
      - public/artifacts/pylint-codequality.json

The GitLab-specific report generation should remain a project-command decision.

For example:

from cikit.env import CIProvider

if env.provider == CIProvider.GITLAB:
    ruff.gitlab_code_quality(env, args.paths)

The normal Ruff or Pylint execution remains provider-independent.

Remote cikit Data 

Remote cikit data synchronization is optional.

When used in GitLab CI, the relevant settings are:

CIKIT_DATA_BASE_URL
CIKIT_DATA_API_TOKEN

These values can be configured through GitLab CI/CD variables.

The API token should not be stored in the repository and should be configured using the appropriate GitLab protection and masking settings for the project.

The remote project key is derived from PROJECT_NAME and the optional tool.cikit.data_scope value in pyproject.toml. It is therefore independent of GitLab project namespace metadata.

The complete addressing and synchronization model is documented in Cikit Data.

GitLab Pages 

Documentation generated through the cikit Sphinx workflow is registered as an HTML FOLDER artifact.

With the default cikit artifact layout, the resulting directory is:

public/artifacts/html

GitLab Pages publication is a separate CI deployment step.

A Pages job can publish the generated directory with:

deploy-pages:
  stage: deploy
  script:
    - echo "Publishing documentation"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  pages:
    publish: public/artifacts/html

The example restricts publication to the default branch.

The Sphinx macro itself contains no GitLab Pages logic. It only builds and registers the HTML documentation.

If PUBLIC_DIR or the artifact layout is customized, the Pages publish path must be adjusted accordingly.

For the documentation build workflow, see Sphinx Documentation Build.

GitLab-Specific Responsibility 

GitLab configuration is responsible for GitLab-specific behavior such as:

job artifact publication
Code Quality report registration
CI/CD variables
Pages deployment
runner and job configuration

cikit remains responsible for executing project commands and producing the corresponding run data and artifacts.

This separation allows the same commands to run locally or under another supported CI provider.