Releasing the CPM Lab

All CPM Lab repositories are released together with one version number, e.g. 0.4.0, by the release pipeline of the lab workspace ros2-workspace-lab. Nothing has to be merged or tagged by hand.

What a Release Covers

Repository	Released as
Components (the submodules of the lab workspace)	Tag and GitLab release with the changelog entries of their packages
`lichtblick`	Tag; its tag pipeline builds the extensions, uploads the `.foxe` files and creates the GitLab release
`ros2-workspace-vehicle`	Submodules pointed to the released components, tag and GitLab release with its changelog entry
`ros2-workspace-lab`	Submodules pointed to the released components and tag; its tag pipeline builds the Debian packages for ROS2 Humble and Jazzy (`amd64` and `arm64`) and publishes them on the apt server, see Install from Debian Packages
`desktop`, `simulation`	Tag once the apt server serves the new packages; their tag pipelines build and smoke-test the images with the released packages and create the GitLab releases, see Docker Images

Every repository goes through the same steps: the merge request dev → main is merged, main is checked to have exactly the files of the merged dev commit, and that dev commit is tagged. The tag is therefore reachable from dev and main.

Before a Release

While developing, add every change to a Forthcoming section at the top of the CHANGELOG.rst of the package you changed, and to the Forthcoming section of the CHANGELOG.rst of the lab workspace (and of the vehicle workspace if you changed it):

Forthcoming
-----------
* Add the lane change maneuver to the example planner

0.3.0 (2026-10-02)
------------------
* ...

The release renames Forthcoming to <version> (<date>) and sets the version of every package.xml. Packages without changes since the last release get the entry * No changes. A package that changed but has no Forthcoming section stops the release.

The Lichtblick extensions are versioned separately: set the version of every extension to the release version before the release, e.g. for 0.4.0 in the lichtblick repository:

for d in extensions/*/; do (cd "$d" && npm version 0.4.0 --no-git-tag-version); done

The release does not check this; a wrong version only fails the check-extension-versions job of the Lichtblick tag pipeline, after the tag exists.

Lichtblick Release and File Names

What	Format	Example
Release tag	`<major>.<minor>.<patch>`, the CPM Lab version without `v`, created by the release pipeline	`0.3.0`
Extension `version` (`package.json`)	the release version	`0.3.0`
Extension `publisher`	`cpm-team`	`cpm-team`
Extension `name`	lower case with underscores; new extensions start with `cpm_lab_`	`cpm_lab_control_center`
`.foxe` file	`<publisher>.<name>.foxe`, without the version, so links stay valid	`cpm-team.cpm_lab_control_center.foxe`
Package registry	`lichtblick-extensions/<tag>/<publisher>.<name>.foxe`	`lichtblick-extensions/0.3.0/cpm-team.cpm_lab_control_center.foxe`

The GitLab release of lichtblick links the .foxe files of the package registry. After the release, copy them into assets/ of the documentation, see Maintaining the Documentation.

Releasing

Make sure all changes are merged into dev in every repository and the dev pipelines are green. The pipelines of desktop and simulation may fail if they need packages of the new release; they are rerun after the packages are published.
In GitLab, open the lab workspace ros2-workspace-lab, Build → Pipelines → Run pipeline on dev.
Set RELEASE_VERSION (e.g. 0.4.0) and DRY_RUN to true and run the pipeline. The release job only checks every repository and lists what it would do, or all problems that block the release.
Fix the problems, then run the pipeline again with DRY_RUN set to false.

The release job then:

Checks every repository: dev pipeline green, merge request dev → main mergeable, main has no changes that dev lacks, changelogs complete, and every submodule of the vehicle workspace is a component of the lab workspace. If anything is wrong, it lists all problems and changes nothing.
Finalizes the changelogs and package.xml versions on dev.
Merges and tags the components and lichtblick.
Points the submodules of the vehicle workspace and the lab workspace to the released component commits, then merges and tags both. It waits for the dev pipeline of the lab workspace, which builds all packages, so the job can take a while.

The tag pipeline of the lab workspace builds and publishes the Debian packages. When the apt server serves them, its wait_for_apt and release_images jobs merge and tag desktop and simulation.

If a step fails, fix the reported problem and run the pipeline again, or retry the failed job. Finished steps are skipped, and tags are never moved.

Tip

A common blocker is a change on main that dev does not have, e.g. a hotfix. Merge main into dev first, then start the release again.

Setup

The release needs the masked, protected CI/CD variable RELEASE_TOKEN in the lab workspace: a group access token of CPM/Project/Lab with the Maintainer role and the api scope. In every released repository, dev and the version tags (*.*.*) must be protected, Maintainers must be allowed to push to dev and merge into main, the merge method must be Merge commit, and merge requests into main must not require approvals.

The release job is defined in .gitlab-ci.yml of the lab workspace and runs ci/release.py; its tests are in ci/test_release.py. The documentation is not part of the release; update it afterwards, see Maintaining the Documentation.