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

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

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.