Docker 기반 CMake 빌드 환경을 사용한 GitHub Actions에서 Qt6 CI 간소화

Source: Dev.to

Problem Statement

Qt6은 강력하지만, GitHub Actions에서 Qt6 프로젝트를 위한 신뢰할 수 있는 CI 파이프라인을 설정하는 것은 생각보다 고통스러울 수 있습니다.

• 복잡한 의존성 요구 사항
• Qt 버전에 따라 달라지는 설정 단계
• CMake + Ninja 환경 불일치
• 로컬 환경과 CI 환경 간 차이
• aqtinstall 사용 시 발생하는 플랫폼‑특정 문제

Qt6 CI에서 가장 큰 문제는 환경 불일치입니다:

• GitHub‑호스트 러너마다 의존성이 다름
• OS와 버전에 따라 Qt6의 동작이 약간씩 다름
• aqtinstall이 플랫폼마다 다른 결과를 생성할 수 있음

이 모든 것을 GitHub Action 안에서 직접 지원하려고 하면 금방 복잡해집니다.

Solution Overview

Docker‑기반 Qt6 CMake CI Action은 GitHub Actions에서 Qt6 프로젝트를 빌드하기 위한 완전히 재현 가능한 환경을 제공합니다.

• 모든 러너에서 동일한 Ubuntu‑기반 환경 사용 (Ubuntu, Windows, macOS)
• 의존성 차이 제로
• 완전 재현 가능한 빌드
• 플랫폼‑특정 놀라움이 더 이상 없음

이 Action은 Qt6 프로젝트를 빌드하는 데 필요한 모든 작업을 자동화합니다:

1. aqtinstall을 사용해 Qt6 설치
2. CMake + Ninja 설정
3. Docker 컨테이너 내부에서 프로젝트 빌드
4. 모든 GitHub‑호스트 러너에서 동작
5. Qt 버전 차이를 자동으로 처리

Features

• Docker‑기반 안정성 – 빌드는 항상 Linux Docker 컨테이너 안에서 실행됩니다.
• CMake + Ninja 사전 설치.
• 핵심 Qt6 모듈 자동 설치 (Core, GUI, Widgets, QML, Quick).
• 추가 모듈을 지정할 수 있음 (예: qtimageformats, qtshadertools).
• Ubuntu, Windows, macOS GitHub‑호스트 러너 지원.
• GUI 테스트 지원 (Xvfb / noVNC).
• 더 빠른 CI를 위한 빌드 캐싱.
• Qt Installer Framework 자동화.

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

• 완전 재현 가능한 환경 – 모든 러너에서 동일한 빌드 결과.
• Ubuntu, Windows, macOS 러너 전반에 걸친 동일한 빌드 동작.
• Qt 버전 설정이 자동으로 처리됨.
• Docker‑기반 안정성이 플랫폼‑특정 놀라움을 없앰.

Getting the Action

🔗 Qt6 CMake CI Action on GitHub Marketplace

Future Plans

• 모든 사용자를 위해 Qt 개발을 더 원활하게 만들기 위해 Action을 지속적으로 개선.
• 더 많은 GUI 테스트 기능 추가.
• 빌드 캐싱 전략 강화.