DEV Community

acc-vcc
acc-vcc

Posted on

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

#qt #cmake #docker #githubactions

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"
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)