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).

Umbrella pipeline

The umbrella .gitlab-ci.yml adds two 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.

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 (e.g. the pySMSpp submodule, which lives 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)

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.