cici config file format

This page is a reference for cici config file syntax. For a tutorial, see the Getting started section of the site.

Fields marked with * are required.

File

Top-level cici configuration object.

This is the root of .cici/config.yaml. It describes the component, declares its pipeline targets, variables, and logical groups, and provides metadata used when generating README documentation.

Field	Description
name*	See Shared fields.
repo_url	Web URL of the source repository for this component. Used to derive include paths and README links.
gitlab_project_path (deprecated)	Deprecated no-op. Previously used to specify the GitLab project path; now derived automatically from repo_url. Field preserved for backwards compatibility.
brief	See Shared fields.
description	See Shared fields.
groups	Declares logical groupings available for targets to reference. Groups are rendered as use-case sections in the README.
targets	Declares the pipeline targets this component provides. Each target becomes a separate output file when bundled.
variables	Declares the CI/CD variables that configure this component's pipeline targets.

repo_url

string

Web URL of the source repository for this component. Used to derive include paths and README links.

Defaults to "".

repo_url: https://gitlab.com/saferatday0/library/cxx

Group

A logical set of pipeline targets.

Groups allow targets to be organised into named categories, which are rendered as use-case sections in the generated README.

Field	Description
name*	See Shared fields.
brief	See Shared fields.
description	See Shared fields.

Target

A single pipeline target provided by this component.

Each target becomes a separate output file when the component is bundled. Targets can be organised into groups, tagged for filtering, and optionally configured with a container image.

Field	Description
name*	See Shared fields.
brief	See Shared fields.
description	See Shared fields.
groups	References one or more group names declared in the top-level groups list. Used to organise targets into use-case sections in the README.
tags	Free-form tags for filtering and curating targets.
container	Container runtime configuration for this target's jobs.
precommit_hook (deprecated)	Configuration for the pre-commit hook.
gitlab_include (deprecated)	Configuration for the GitLab CI/CD include.

groups

string array

References one or more group names declared in the top-level groups list. Used to organise targets into use-case sections in the README.

Defaults to [].

groups:
  - "quality"

tags

string array

Free-form tags for filtering and curating targets.

Defaults to [].

tags:
  - "lint"

Container

Container runtime configuration for a pipeline target.

Field	Description
image*	Container image for this target's jobs. ${CONTAINER_PROXY} is automatically prepended to unqualified image names.
entrypoint	Overrides the container's default entrypoint.

image*

string

Container image for this target's jobs. ${CONTAINER_PROXY} is automatically prepended to unqualified image names.

image: python:3.11-slim

entrypoint

string array

Overrides the container's default entrypoint.

Defaults to [].

entrypoint:
  - ""

Variable

A CI/CD variable that configures this component's pipeline targets.

Field	Description
name*	See Shared fields.
brief	See Shared fields.
default	Default value used when the variable is not set by the consumer. Leave empty if the variable is required.
description	See Shared fields.
required	When true, indicates that this variable must be explicitly set by the consumer. Rendered as a requirement notice in the README.
examples	Example values with brief explanations, shown in the README variable reference.

default

string

Default value used when the variable is not set by the consumer. Leave empty if the variable is required.

Defaults to "".

default: 3.11

VariableExample

An example value for a pipeline variable.

Examples are rendered in the README variable reference to help consumers understand valid values and common configurations.

Field	Description
value*	An example value for the variable.
brief	See Shared fields.

value*

string

An example value for the variable.

value: 3.11

Shared fields

Fields that appear on more than one type are documented here.

brief

string

Short, one-line summary. Supports Markdown.

Defaults to "".

Used by File, Group, Target, Variable, and VariableExample.

brief: Run the linter on the project.

---

description

string

Long-form description. Supports Markdown.

Defaults to "".

Used by File, Group, Target, and Variable.

---

name*

string

Unique name identifying this item.

Used by File, Group, Target, and Variable.

Deprecated

Warning

The following fields and types are retained for backward compatibility and will be removed in a future release. Do not use them in new configurations.

Deprecated fields

Field	Description
File.gitlab_project_path	Deprecated no-op. Previously used to specify the GitLab project path; now derived automatically from repo_url. Field preserved for backwards compatibility.
Target.precommit_hook	Configuration for the pre-commit hook.
Target.gitlab_include	Configuration for the GitLab CI/CD include.

Deprecated types

The following types are only used by deprecated fields above.

GitLabIncludeTarget

Custom name for a GitLab CI/CD Include target.

Field	Description
name*	Name of GitLab include target.

PreCommitHookTarget

Custom name for a pre-commit hook target.

Field	Description
name*	Name of pre-commit hook.