Simplifying Qt6 CI on GitHub Actions with a Docker-Based CMake Build Environment

Source: Dev.to

Problem Statement

Qt6 is powerful, but setting up a reliable CI pipeline for Qt6 projects on GitHub Actions can be surprisingly painful.

• Complex dependency requirements
• Different setup steps depending on the Qt version
• CMake + Ninja environment inconsistencies
• Differences between local and CI environments
• Platform‑specific issues when using aqtinstall

The biggest challenge in Qt6 CI is environment inconsistency:

• Dependencies differ across GitHub‑hosted runners
• Qt6 behaves slightly differently depending on OS and version
• aqtinstall can produce different results on different platforms

Trying to support all of this directly inside a GitHub Action becomes messy fast.

Solution Overview

A Docker‑based Qt6 CMake CI Action provides a fully reproducible environment for building Qt6 projects on GitHub Actions.

• The same Ubuntu‑based environment on all runners (Ubuntu, Windows, macOS)
• Zero dependency differences
• Fully reproducible builds
• No more platform‑specific surprises

The Action automates everything needed to build a Qt6 project:

1. Installs Qt6 using aqtinstall
2. Sets up CMake + Ninja
3. Builds the project inside a Docker container
4. Works on all GitHub‑hosted runners
5. Handles Qt version differences automatically

Features

• Docker‑based stability – builds always run inside a Linux Docker container.
• CMake + Ninja are preinstalled.
• Automatic installation of core Qt6 modules (Core, GUI, Widgets, QML, Quick).
• Optional add‑on modules can be specified (e.g., qtimageformats, qtshadertools).
• Supports Ubuntu, Windows, and macOS GitHub‑hosted runners.
• GUI testing support (Xvfb / noVNC).
• Build caching for faster CI.
• Qt Installer Framework automation.

Usage

Minimal workflow

name: Build Qt6 Project
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Qt6 and build
        uses: acc-vcc/qt6-cmake-ci-action@v1
        with:
          qt-version: "6.6.1"
          # modules: "qtimageformats qtshadertools"  # Only needed for add‑on modules

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build
          path: build/

Action inputs

Example of specifying additional modules

with:
  qt-version: "6.6.1"
  modules: "qtimageformats qtshadertools"

Benefits

• Fully reproducible environment – identical builds on every runner.
• Same build behavior across Ubuntu, Windows, and macOS runners.
• Qt version setup handled automatically.
• Docker‑based stability eliminates platform‑specific surprises.

Getting the Action

🔗 Qt6 CMake CI Action on GitHub Marketplace

Future Plans

• Continue improving the Action to make Qt development smoother for everyone.
• Add more GUI testing capabilities.
• Enhance build caching strategies.