GitHub Actions Workflows

Location: .github/workflows/
Platform: GitHub Actions
Type: CI/CD Pipeline Latest Version: 0.0.5-1

Overview

ProjT Launcher uses a modular GitHub Actions workflow architecture. The CI system is split into specialized sub-workflows that are orchestrated by a main coordinator workflow.

Workflow Architecture

┌─────────────────────────────────────────────────────────────┐
│                      ci-new.yml                             │
│                  (Main Orchestrator)                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ ci-prepare  │  │  ci-lint    │  │     ci-release      │  │
│  │   .yml      │  │    .yml     │  │        .yml         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Library Workflows                      │    │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────┐  │    │
│  │  │ci-zlib  │ │ci-bzip2 │ │ci-quazip│ │ ci-cmark  │  │    │
│  │  │  .yml   │ │  .yml   │ │  .yml   │ │   .yml    │  │    │
│  │  └─────────┘ └─────────┘ └─────────┘ └───────────┘  │    │
│  │  ┌──────────────┐ ┌────────────────┐                │    │
│  │  │ci-tomlplusplus│ │ ci-libqrencode │               │    │
│  │  │     .yml      │ │      .yml      │               │    │
│  │  └──────────────┘ └────────────────┘                │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ ci-website  │  │ci-scheduled │  │      (unlock)       │  │
│  │   .yml      │  │    .yml     │  │      Merge Gate     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Workflow Files

Main Orchestrator

File	Description
`ci-new.yml`	Main coordinator that calls all sub-workflows with conditional logic

Core Workflows

File	Purpose	Triggers
`ci-prepare.yml`	Initial setup, dependency caching	Called by main
`ci-lint.yml`	Code quality checks (clang-format, linters)	Push, PR, Manual
`ci-release.yml`	Build releases, create artifacts	Release, Manual
`ci-website.yml`	Build and deploy website	Push, PR
`ci-scheduled.yml`	Scheduled maintenance tasks	Cron

Library Workflows

Each bundled library has its own independent CI:

File	Library	Tests
`ci-zlib.yml`	zlib	Compression tests
`ci-bzip2.yml`	bzip2	Compression + valgrind
`ci-quazip.yml`	QuaZip	Qt ZIP operations
`ci-cmark.yml`	cmark	Markdown parsing
`ci-tomlplusplus.yml`	toml++	TOML parsing
`ci-libqrencode.yml`	libqrencode	QR generation

Workflow Design Principles

1. Modular Architecture

Each workflow is self-contained and can be run independently:

# Sub-workflow pattern
on:
  workflow_call:
    inputs:
      ref:
        required: false
        type: string
  push:
    paths:
      - 'library-name/**'
  pull_request:
    paths:
      - 'library-name/**'

2. Centralized Control

The main orchestrator (ci-new.yml) controls when each sub-workflow runs:

jobs:
  call-zlib:
    if: needs.prepare.outputs.run-zlib == 'true'
    uses: ./.github/workflows/ci-zlib.yml

3. Path Filtering

Workflows only run when relevant files change:

paths:
  - 'zlib/**'
  - '.github/workflows/ci-zlib.yml'

4. Merge Gate

The unlock job aggregates all results for merge protection:

{% raw %}

unlock:
  needs: [lint, build, test-zlib, test-bzip2, ...]
  if: always()
  runs-on: ubuntu-latest
  steps:
    - name: Check all jobs
      run: |
        if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
          exit 1
        fi

{% endraw %}

Triggers

Trigger	Workflows	Description
`push`	All	Commits to main branches
`pull_request`	All	Pull request changes
`release`	Release	GitHub releases
`schedule`	Scheduled	Cron jobs
`workflow_dispatch`	All	Manual triggers
`workflow_call`	Sub-workflows	Called by orchestrator

Environment Variables

Variable	Description
`GITHUB_TOKEN`	Automatic GitHub token
`MSA_CLIENT_ID`	Microsoft Auth client ID
`CACHIX_AUTH_TOKEN`	Nix cache auth

Adding New Workflows

Create the workflow file in .github/workflows/
Add workflow_call trigger for orchestrator integration
Add push/PR triggers for independent execution
Update ci-new.yml to include the new workflow
Document in this handbook

Template