ci-multiplatform
ci-multiplatform is a flexible, multi-architecture CI template and image build system for GitLab CI. It enables building and testing software across a wide range of platforms, including x86, RISC-V, ARM, MIPS, PowerPC, and Windows cross-compilation targets (including Windows on ARM). The system is instance-independent, generic, and modular, making it easy to extend for new platforms or toolchains.
Features
Multi-architecture support: Build and test for various Linux and Windows targets using native images executed on native or QEMU-based GitLab runners.
Instance-independent configuration: Use templates on any GitLab instance by setting runner tags for supported architectures.
OCI image templates: Layered Docker/OCI images for base, toolchain (GNU, LLVM), and build environments (Meson), with options to extend with project-specific dependencies.
Reusable CI templates: Optional GitLab CI templates for a full build, test, and coverage summary flow, supporting matrix and parallel execution, for selected build systems.
Benefits for Developers
Effortlessly test new revisions across multiple virtual targets in parallel.
Minimize the risk of introducing regressions on other architectures during refactoring.
Increase confidence when submitting code upstream.
Improve the likelihood of having changes for new architectures accepted.
Benefits for Projects
Seamlessly integrate the CI pipeline by adapting configurations from other projects.
Centralize and streamline CI maintenance across all projects.
Reduce the time maintainers spend on code review.
Lower the risk of regressions being introduced into the codebase.
Success Story
Before the introduction of these CI templates, Pixman’s continuous integration was limited to a single architecture, despite the library’s reliance on architecture-specific code paths (such as SIMD ISA extensions) that demand thorough cross-platform testing. When RISC-V support was developed, maintainers hesitated to merge the patches due to their inability to test on RISC-V and limited familiarity with its SIMD features.
With the deployment of the new multi-architecture CI setup, maintainers gained confidence in the correctness of the RISC-V patches, as every commit was automatically built and tested across all supported platforms in multiple configurations. This not only accelerated the acceptance of RISC-V contributions but also uncovered several regressions for other architectures, including issues specific to LLVM-based builds. The improved CI coverage has since helped maintain Pixman’s reliability and portability, making it easier to maintain and extend support for new architectures.
Directory Structure
.gitlab-ci.ymland.gitlab-ci.d/: Main CI configuration. Builds base OCI images in common configurations and tests them, along with build and test templates on example projects.oci/: Containerfile definitions for base OCI images.templates/: Reusable YAML templates for OCI, build, test, and coverage stages.doc/: Sphinx documentation source files.
Supported Build Systems
Currently, the templates are optimized for the Meson build system.
However, you can leverage the OCI image build stage to create custom images – either starting from scratch or extending the provided GNU/LLVM images – to add support for your preferred build system.
There is a plan to include CMake support in the near future.
Supported Platforms
The project leverages Debian’s extensive architecture support as the base. Additional platforms can be added by extending the templates and OCI image definitions.
Linux
x86 (i386, amd64)
ARM (armel/ARMv5, armhf/ARMv7, arm64/AARCH64)
RISC-V (riscv64)
MIPS (mips, mipsel, mips64el)
PowerPC (ppc, ppc64, ppc64le)
Windows (cross-compilation)
x86 (i686, amd64)
ARM64 (LLVM-only)
Supported GitLab instances
The templates are intended to be compatible with any GitLab instance. This repository is hosted and actively tested on the instances listed below. Compatibility with other GitLab instances is not guaranteed – if you encounter issues, please open an issue in the main GitLab.com repository.
Supported instances:
Example Usage
You can explore practical examples in the examples directory of this
repository. Each supported build system has dedicated examples, ranging from
minimal setups to more advanced configurations.
Currently, the system is actively evaluated on the Pixman
project. For a real-world usage scenario, see the ci-external branch,
particularly the .gitlab-ci.d directory.
Below is a summary of available and planned examples:
Example |
Description |
Build System |
Status |
|---|---|---|---|
library |
Meson |
✅ |
|
minimal example |
Meson |
✅ |
|
advanced example |
Meson |
✅ |
|
library |
CMake |
🕒 |
Example pipeline in GitLab GUI:
Credits
This project was originally created by Marek Pikuła at Samsung R&D Institute Poland, as part of the RISE (RISC-V Software Ecosystem) Project.
The initial CI pipeline was developed to support the Pixman project, specifically for enabling CI support for RISC-V RVV extension integration.
The work was presented at RISC-V Summit Europe 2025 as a poster titled Enabling RISC-V CI in Open-Source Projects: Challenges and Solutions. The abstract and poster are available on GitHub.
License
This project is primarily licensed under the MIT License. The Buildah Containerfile is provided under the Apache License 2.0.
Note
Please note that this documentation is a work in progress and may not address every aspect of the project. If you have questions or need further clarification, feel free to open an issue in the repository.