Azure DevOps Integration

Overview

cikit can run project commands inside Azure DevOps Pipelines without requiring a separate command implementation.

When Azure DevOps is active, cikit selects AzureDevOpsProvider automatically and maps Azure pipeline metadata to the common cikit provider interface.

This guide covers only Azure-DevOps-specific integration:

• provider detection and metadata

• branch and Git metadata handling

• Azure log groups

• Pipeline Artifact publication

• Azure pipeline variables for remote cikit data

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

Provider Detection

Azure DevOps is detected through:

TF_BUILD=true

cikit then uses AzureDevOpsProvider.

Azure DevOps exposes predefined pipeline variables to scripts as environment variables. cikit reads the corresponding uppercase environment names.

Project and Pipeline Identity

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

Provider property	Azure DevOps variable	Meaning
provider_scope	SYSTEM_TEAMPROJECT	Azure DevOps project name.
provider_project	BUILD_REPOSITORY_NAME	Repository name.
pipeline_id	BUILD_BUILDID	Technical pipeline run id.
pipeline_alias	BUILD_BUILDNUMBER	Human-readable build number.

If BUILD_BUILDNUMBER is unavailable, pipeline_alias falls back to pipeline_id.

Project commands should normally use the cikit environment instead of reading Azure variables directly.

For the complete provider model, see Providers.

Branch Name

Azure DevOps branch resolution first uses:

BUILD_SOURCEBRANCH

cikit removes the standard Git prefixes:

refs/heads/main
-> main

refs/heads/feature/example
-> feature/example

refs/tags/v1.2.3
-> v1.2.3

If BUILD_SOURCEBRANCH does not contain one of these supported refs, BUILD_SOURCEBRANCHNAME is used.

If neither Azure value is available, branch resolution falls back to the local Git checkout.

Git Metadata

AzureDevOpsProvider derives commit metadata from the checked-out Git repository.

This includes:

• commit SHA

• short commit SHA

• commit title

• commit message

• commit author

• commit timestamp

This differs from GitLabProvider, which obtains these values directly from CI environment variables.

Azure pipeline jobs using cikit should therefore keep the repository checkout available when commit metadata is required.

The checkout location itself does not need to be hard-coded into project commands; cikit resolves the repository through the active environment.

Azure Log Groups

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

Under Azure DevOps, cikit emits:

##[group]Title
...
##[endgroup]

Azure Pipelines renders these markers as collapsible log groups.

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

The common collapsed setting does not control the initial collapsed state for Azure DevOps groups.

See CI Commands for CiSection and command status behavior.

Running cikit Commands

cikit commands can be executed from normal Azure Pipeline script steps.

For example:

steps:
  - script: uv run cikit init
    displayName: Initialize cikit

  - script: uv run cikit ruff src tests ci_commands
    displayName: Run Ruff

The exact command set and job structure remain project-specific.

The same project commands can be executed locally or under another supported CI provider.

Pipeline Artifacts

cikit stores persistent generated output below PUBLIC_DIR.

With the default configuration this is:

public/

On Azure DevOps Services, the complete cikit output can be published as a Pipeline Artifact:

steps:
  - publish: public
    artifact: cikit
    displayName: Publish cikit output

The publish YAML step is Azure Pipelines functionality; cikit itself does not upload Pipeline Artifacts.

Publishing the complete public directory keeps the Azure pipeline configuration independent of the internal cikit artifact layout.

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

For the cikit artifact model, see Artifacts.

Azure DevOps Server

The publish shortcut uses Azure Pipeline Artifacts and is intended for Azure DevOps Services.

Azure DevOps Server installations that do not support Pipeline Artifacts must use the corresponding Build Artifact task instead.

This difference belongs to Azure pipeline configuration and does not change cikit artifact generation.

Publishing Documentation

The cikit Sphinx workflow registers generated HTML documentation as a FOLDER artifact.

With the default cikit layout, the resulting directory is:

public/artifacts/html

A pipeline can publish only that directory when the documentation should be exposed as a separate Pipeline Artifact:

steps:
  - script: uv run cikit sphinx docs
    displayName: Build documentation

  - publish: public/artifacts/html
    artifact: documentation
    displayName: Publish documentation

Deployment to a web hosting target is separate from the cikit Sphinx build and from Azure Pipeline Artifact publication.

For the documentation build workflow, see Sphinx Documentation Build.

Remote cikit Data

Remote cikit data synchronization is optional.

When used in Azure DevOps, the relevant settings are:

CIKIT_DATA_BASE_URL
CIKIT_DATA_API_TOKEN

The API token should be stored as an Azure secret variable rather than in the repository.

Secret Variable Mapping

Azure secret variables are not automatically exported as environment variables to script steps.

Because cikit reads CIKIT_DATA_API_TOKEN from the process environment, the secret must be mapped explicitly.

For example, if the Azure secret variable is also named CIKIT_DATA_API_TOKEN:

steps:
  - script: uv run cikit init
    displayName: Initialize cikit
    env:
      CIKIT_DATA_API_TOKEN: $(CIKIT_DATA_API_TOKEN)

The same pattern can be used for any secret consumed by a cikit command.

Non-secret Azure variables are normally exposed to scripts as environment variables automatically.

Cikit Data Addressing

The remote cikit Data project key is derived from PROJECT_NAME and the optional tool.cikit.data_scope value in pyproject.toml. Azure project and repository metadata do not participate in data addressing.

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

Azure-Specific Responsibility

Azure Pipeline configuration is responsible for Azure-specific behavior such as:

• agents and pools

• stages and jobs

• pipeline variables and secrets

• Pipeline Artifact publication

• deployment targets

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

Keeping these responsibilities separate allows the same command modules to run locally, in Azure DevOps, or under another supported provider.

See Also

• CI Commands

• Sphinx Documentation Build

• Providers

• Artifacts

• Cikit Data