GithubWorkflowTool

A cross-platform desktop application that clones Git repositories to per-user cache directories and simulates GitHub Actions workflows locally.

Features

• Repository Management: Clone repositories to platform-specific cache directories

  • Windows: %APPDATA%\GithubWorkflowTool\repos\
  • Linux: $XDG_DATA_HOME/githubworkflowtool/repos/ or ~/.local/share/githubworkflowtool/repos/

• Workflow Simulation: Discover and execute GitHub Actions workflows locally

  • Automatic discovery of .github/workflows/*.yml files
  • Support for jobs, steps, needs, env variables, and outputs
  • Matrix strategy expansion
  • Artifacts upload/download (local equivalent)
  • Caching support (local equivalent of actions/cache)

• Multiple Execution Backends:

  • Container Backend: Fast iteration using Docker or Podman
  • QEMU Backend: Higher fidelity VM-based execution

• Dual Interface:

  • CLI: Command-line interface for automation and scripting
  • GUI: Qt6-based graphical interface for visual inspection and interaction

Technology Stack

• C++17
• Qt 6.6+
• CMake 3.22+
• Conan package manager
• Ninja build system
• yaml-cpp for workflow parsing
• Docker/Podman (optional, for container backend)
• QEMU (optional, for VM backend)

Quick Start

See BUILD.md for detailed build instructions.

# Install dependencies
conan install . --output-folder=build --build=missing

# Build
cmake --preset=default
cmake --build build

# Run CLI
./build/gwt clone https://github.com/user/repo
./build/gwt workflows /path/to/repo
./build/gwt run /path/to/repo /path/to/workflow.yml

# Run GUI
./build/gwt-gui

Architecture

Core Components

• StorageProvider: Platform-specific storage path management
• RepoManager: Git repository cloning and management
• WorkflowDiscovery: Workflow file discovery
• WorkflowParser: YAML workflow parsing
• JobExecutor: Workflow execution orchestration
• MatrixStrategy: Matrix strategy expansion
• ArtifactManager: Artifact upload/download
• CacheManager: Cache management

Backends

• ContainerBackend: Executes workflows in Docker/Podman containers
• QemuBackend: Executes workflows in QEMU virtual machines

Repository Structure

GithubWorkflowTool/
├── CMakeLists.txt          # Main CMake configuration
├── conanfile.txt           # Conan dependencies
├── CMakePresets.json       # CMake presets
├── include/                # Public headers
│   ├── core/              # Core functionality headers
│   ├── backends/          # Execution backend headers
│   ├── cli/               # CLI headers
│   └── gui/               # GUI headers
├── src/                    # Implementation files
│   ├── core/              # Core functionality
│   ├── backends/          # Execution backends
│   ├── cli/               # CLI implementation
│   └── gui/               # GUI implementation
├── BUILD.md               # Build instructions
└── README.md              # This file

Supported Platforms

• Windows 11+
• Linux (Ubuntu/Debian-based distributions)
• macOS (host support; VM images may have limitations)

Limitations (v1)

GithubWorkflowTool v1 has intentional limitations to ensure deterministic, debuggable local execution:

• Not all GitHub Actions features are supported (see LIMITATIONS.md §3.1)
• Some third-party actions may require container mode or preinstalled tools (§3.2)
• Service containers not yet implemented (§3.3)
• macOS runner images not supported (§3.4)
• Network access in runners may be limited (§3.5)

Before running workflows locally, use gwt doctor to check compatibility and get actionable guidance.

For detailed information, workarounds, and resolution roadmap, see LIMITATIONS.md.

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please ensure your code follows the existing style and includes appropriate tests.