SMS++ GitLab Guide

SMS++ is developed on GitLab, where every module is its own repository and the SMS++ Project umbrella ties them together as git submodules. This page explains how the GitLab CI/CD pipelines are organized. For the contribution workflow see the Developer's Guide and CONTRIBUTING.md.

[[TOC]]

Per-module pipelines

Each module ships a .gitlab-ci.yml with three stages — build, test, deploy — that run on the develop branch and on tags, and only when relevant files change (cmake/, include/, src/, test/, tools/, CMakeLists.txt):

• build — clones the umbrella, configures it with the module's BUILD_<Module>=ON flag and builds/installs it;
• test — runs ctest on the resulting build;
• deploy — on tags, packages the build with CPack.

Cloning the private build image and the umbrella uses the SMSPP_DEPLOY_KEY CI/CD variable (an SSH deploy key).

New modules do not write this file by hand: the ModuleTemplate skeleton ships it ready-made, with the -DBUILD_* flags line as the only per-module bit (see Creating a new module).

Umbrella pipeline

The umbrella .gitlab-ci.yml adds these project-level jobs:

• pages — builds the Doxygen API reference and the MkDocs User Manual and publishes them to GitLab Pages (manual trigger);
• release_job — on tags, assembles a source archive of the whole project (submodules included) and publishes a GitLab Release, using glab and the ANTONIO_PERSONAL_ACCESS_TOKEN variable.
• packaging — the jobs packaging:*, which build the package recipes of packaging/ and the smspp port of the vcpkg registry from the tarball of the commit, made as the release job makes it: Spack, Conan, Nix, the AUR, xmake and vcpkg on Linux and the Homebrew formula of the tap on macOS, each with UCBlock, MILPSolver and MCFClassSolver, a small consumer that makes a UCBlock and a HiGHSMILPSolver by the factories, and the Unit Commitment tool solving its example with HiGHS. Since the builds are long, the jobs run only when a push or a merge request touches packaging/, the CMakeLists.txt of the umbrella or the gitlink of vcpkg-registry, and in a pipeline run with the variable PACKAGING set to 1 (Build > Pipelines > Run pipeline, or a schedule); the details are in the README.md of packaging/.

Mirroring to GitHub

The project is mirrored read-only to the SMSpp-Project organization on GitHub for visibility. GitLab stays the single source of truth: please open issues and merge requests on GitLab.

The mirror is implemented entirely in CI, with two complementary mechanisms:

• a mirror job in every repository (the mirror stage) that, on each push, does a git clone --mirror from GitLab and a git push --mirror to the matching GitHub repository. It declares needs: [] so it starts immediately, in parallel with build, without blocking the other stages;
• a mirror_all orchestrator job in the umbrella that mirrors every submodule first and the umbrella last, so a --recurse-submodules clone of the GitHub mirror is always consistent. It runs on a schedule or manually, and skips repositories that are not hosted on GitLab (the pySMSpp and pypsa2smspp submodules, which live on GitHub) and the wiki.

Both jobs are guarded by if: '$GITHUB_MIRROR_TOKEN && …', so they only run when the group-level CI/CD variable GITHUB_MIRROR_TOKEN (a GitHub token with write access to the organization) is set; until then they stay dormant and no pipeline turns red.

CI/CD variables

Variable	Scope	Used by
SMSPP_DEPLOY_KEY	group	cloning the umbrella in module builds
ANTONIO_PERSONAL_ACCESS_TOKEN	group	release_job (GitLab releases via glab)
GITHUB_MIRROR_TOKEN	group	the mirror / mirror_all jobs (push to GitHub)
PACKAGING	pipeline	set to 1 when running a pipeline by hand, it runs the packaging:* jobs

Note: SMS++ support for GitLab CI/CD has historically been uneven across modules; the build/test coverage of some modules is still a work in progress, while the mirror job is present in all of them.