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

acc-vcc — Sun, 01 Feb 2026 14:00:24 +0000

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

To solve these problems, I built a Docker-based Qt6 CMake CI Action that provides a fully reproducible environment for building Qt6 projects on GitHub Actions.

🔗 GitHub Marketplace

https://github.com/marketplace/actions/qt6-cmake-ci-action

Why a Docker-Based Approach?

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.

So instead, I took a different approach:

Fix the entire build environment using Docker.

This gives us:

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

For Qt6 CI, this approach is extremely stable.

What This Action Does

This Action automates everything needed to build a Qt6 project:

Installs Qt6 using aqtinstall
Sets up CMake + Ninja
Builds your project inside a Docker container
Works on all GitHub-hosted runners
Handles Qt version differences automatically

You only need to specify the Qt version.

Quick Start

Minimal workflow:

- uses: acc-vcc/qt6-cmake-ci-action@v1
  with:
    qt-version: "6.6.1"

Qt Core / GUI / Widgets / QML are installed automatically.

No module configuration is required for common use cases.

Full Example 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/

Inputs

Name	Required	Description
qt-version	Yes	Qt6 version to install (e.g., 6.6.1)
source-dir	No	Directory containing CMakeLists.txt (defaults to repository root)
modules	No	Qt6 add-on modules (only needed when required)

About `modules`

The Docker image installs all essential Qt6 modules:

Core
GUI
Widgets
QML
Quick

You only need to specify modules if you want additional add-ons:

modules: "qtimageformats qtshadertools"

Supported Environments

GitHub-hosted runners
- Ubuntu
- Windows
- macOS
Build always runs inside a Linux Docker container
CMake + Ninja are preinstalled

This ensures consistent builds across all platforms.

Summary

Qt6 CI can be complicated, but this Action makes it simple:

Fully reproducible environment
Same build behavior on all runners
Qt version setup handled automatically
Docker-based stability

If you're building Qt6 projects on GitHub Actions, give it a try.

Future Plans

Windows/macOS Qt6 builds
GUI testing support (Xvfb / noVNC)
Build caching for faster CI
Qt Installer Framework automation

I plan to continue improving the Action to make Qt development smoother for everyone.

DEV Community: acc-vcc