Add documentation, examples, and fix missing includes

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
2026-04-24 13:45:02 +00:00 · 2025-12-27 03:06:06 +00:00
parent 9b992001f3
commit eb992af859
9 changed files with 493 additions and 0 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-test:
+    name: Build and Test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        build_type: [Debug, Release]
+    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      
+      - name: Install Conan
+        run: pip install conan
+      
+      - name: Configure Conan
+        run: conan profile detect --force
+      
+      - name: Install Dependencies
+        run: conan install . --output-folder=build --build=missing -s build_type=${{ matrix.build_type }}
+      
+      - name: Configure CMake
+        run: cmake --preset=${{ matrix.build_type == 'Debug' && 'debug' || 'default' }}
+      
+      - name: Build
+        run: cmake --build build${{ matrix.build_type == 'Debug' && '-debug' || '' }}
--- a/USAGE.md
+++ b/USAGE.md
@@ -0,0 +1,321 @@
+# GithubWorkflowTool User Guide
+
+## Overview
+
+GithubWorkflowTool is a desktop application that allows you to clone Git repositories and execute their GitHub Actions workflows locally on your machine. This is useful for:
+
+- Testing workflows before pushing to GitHub
+- Debugging workflow issues offline
+- Understanding how workflows behave in different environments
+- Rapid iteration on workflow changes
+
+## Installation
+
+See [BUILD.md](BUILD.md) for build and installation instructions.
+
+## Core Concepts
+
+### Repository Storage
+
+GithubWorkflowTool clones repositories to platform-specific cache directories:
+
+- **Windows**: `%APPDATA%\GithubWorkflowTool\repos\`
+- **Linux**: `$XDG_DATA_HOME/githubworkflowtool/repos/` (or `~/.local/share/githubworkflowtool/repos/`)
+
+Each repository is stored with a unique key based on its URL, preventing conflicts.
+
+### Execution Backends
+
+Two backends are available for running workflows:
+
+1. **Container Backend** (Default)
+   - Uses Docker or Podman
+   - Fast iteration
+   - Lower resource usage
+   - Automatically maps GitHub runner specs to container images
+
+2. **QEMU Backend**
+   - Uses QEMU virtual machines
+   - Higher fidelity to actual GitHub runners
+   - Requires VM images (not included)
+   - Better isolation
+
+## Command-Line Interface (CLI)
+
+### Basic Commands
+
+#### Clone a Repository
+```bash
+gwt clone https://github.com/owner/repo
+```
+
+Clone a specific branch:
+```bash
+gwt clone https://github.com/owner/repo --branch develop
+```
+
+#### List Cloned Repositories
+```bash
+gwt list
+```
+
+#### Discover Workflows
+```bash
+gwt workflows /path/to/repo
+```
+
+#### Run a Workflow
+```bash
+gwt run /path/to/repo /path/to/repo/.github/workflows/ci.yml
+```
+
+Run with QEMU backend:
+```bash
+gwt run /path/to/repo /path/to/repo/.github/workflows/ci.yml --qemu
+```
+
+### Advanced Usage
+
+#### Triggering Specific Events
+By default, workflows are triggered with a "push" event. You can specify different trigger events:
+
+```bash
+gwt run /path/to/repo /path/to/workflow.yml --event pull_request
+```
+
+#### Environment Variables
+Pass environment variables to the workflow:
+
+```bash
+gwt run /path/to/repo /path/to/workflow.yml --env BUILD_TYPE=Release --env DEBUG=1
+```
+
+## Graphical User Interface (GUI)
+
+Launch the GUI:
+```bash
+gwt-gui
+```
+
+### GUI Workflow
+
+1. **Clone or Open Repository**
+   - Click "Clone Repository" to clone from a URL
+   - Or use File > Open to browse for a local repository
+
+2. **Select Repository**
+   - View all cloned repositories in the left panel
+   - Click a repository to load its workflows
+
+3. **View Workflows**
+   - Available workflows appear in the middle panel
+   - Each workflow shows its name and trigger events
+
+4. **Configure Execution**
+   - Select a workflow
+   - Choose backend (Container or QEMU)
+   - Set any environment variables
+
+5. **Run and Monitor**
+   - Click "Run Workflow"
+   - View real-time output in the bottom panel
+   - See job progress and status updates
+
+## Workflow Feature Support
+
+### Supported Features
+
+✅ **Basic Workflow Structure**
+- Jobs and steps
+- Job dependencies (needs)
+- Environment variables (global and per-job)
+- Working directory
+- Shell selection
+
+✅ **Triggers**
+- push
+- pull_request
+- workflow_dispatch
+- schedule (basic support)
+
+✅ **Matrix Strategies**
+- strategy.matrix expansion
+- Multiple dimensions
+- Include/exclude (partial)
+
+✅ **Artifacts**
+- Upload artifacts (stored locally)
+- Download artifacts between jobs
+- Artifact retention
+
+✅ **Caching**
+- Cache save and restore
+- Key-based caching
+- Path patterns
+
+✅ **Common Actions** (Container mode)
+- actions/checkout@v3
+- actions/upload-artifact@v3
+- actions/download-artifact@v3
+- actions/cache@v3
+
+### Limited Support
+
+⚠️ **Conditional Execution**
+- Basic `if` conditions
+- Context variables (partial)
+
+⚠️ **Third-Party Actions**
+- Some actions work in container mode
+- Others may require manual setup
+
+### Not Supported (v1)
+
+❌ Service containers
+❌ Secrets management
+❌ OIDC authentication
+❌ Self-hosted runner features
+❌ macOS runner images
+
+## Examples
+
+### Example 1: Simple CI Workflow
+
+Create `.github/workflows/ci.yml`:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build
+        run: make build
+      - name: Test
+        run: make test
+```
+
+Run it:
+```bash
+gwt clone https://github.com/user/repo
+gwt run ~/.local/share/githubworkflowtool/repos/github.com/user/repo_* ~/.local/share/githubworkflowtool/repos/github.com/user/repo_*/.github/workflows/ci.yml
+```
+
+### Example 2: Matrix Strategy
+
+```yaml
+name: Test Matrix
+
+on: push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.8', '3.9', '3.10']
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - name: Test Python ${{ matrix.python }} on ${{ matrix.os }}
+        run: python --version
+```
+
+This expands to 6 jobs (3 Python versions × 2 OS types).
+
+### Example 3: Dependent Jobs
+
+```yaml
+name: Deploy
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: echo "Building..."
+  
+  test:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Test
+        run: echo "Testing..."
+  
+  deploy:
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        run: echo "Deploying..."
+```
+
+Jobs run in order: build → test → deploy
+
+## Troubleshooting
+
+### Container Backend Issues
+
+**Problem**: "Docker not found"
+**Solution**: Install Docker or Podman
+
+**Problem**: "Permission denied accessing Docker"
+**Solution**: Add user to docker group: `sudo usermod -aG docker $USER`
+
+**Problem**: "Cannot pull image"
+**Solution**: Check internet connection or use `docker pull ubuntu:22.04` manually
+
+### QEMU Backend Issues
+
+**Problem**: "QEMU not found"
+**Solution**: Install QEMU: `sudo apt install qemu-system-x86`
+
+**Problem**: "VM image not found"
+**Solution**: QEMU backend requires pre-built VM images. See documentation for creating images.
+
+### Workflow Issues
+
+**Problem**: "Workflow parsing errors"
+**Solution**: Validate YAML syntax using `yamllint` or GitHub's workflow validator
+
+**Problem**: "Action not found"
+**Solution**: Some actions may not work locally. Try using `run` steps instead.
+
+**Problem**: "Step timeout"
+**Solution**: Increase timeout in step definition or check for hanging processes
+
+## Tips and Best Practices
+
+1. **Use Container Backend for Development**
+   - Faster startup and iteration
+   - Easier debugging
+
+2. **Use QEMU Backend for Final Testing**
+   - Higher fidelity to GitHub runners
+   - Better for compatibility testing
+
+3. **Test Matrix Strategies Locally**
+   - Catch issues before pushing to GitHub
+   - Save CI minutes
+
+4. **Cache Dependencies**
+   - Use actions/cache or similar
+   - Speeds up repeated runs
+
+5. **Keep Workflows Simple**
+   - Complex workflows may have compatibility issues
+   - Break into smaller jobs for easier debugging
+
+## Further Reading
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Workflow Syntax Reference](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)
+- [BUILD.md](BUILD.md) - Build instructions
+- [examples/](examples/) - Example workflows
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,53 @@
+# Example Workflows
+
+This directory contains example GitHub Actions workflow files that can be used to test the GithubWorkflowTool.
+
+## example-workflow.yml
+
+A comprehensive example workflow that demonstrates:
+
+1. **Multiple Triggers**:
+   - Push events on main and develop branches
+   - Pull request events
+   - Manual workflow_dispatch
+
+2. **Global Environment Variables**:
+   - `BUILD_TYPE` set to Release
+
+3. **Multiple Jobs with Dependencies**:
+   - `build`: Initial build and test job
+   - `test-matrix`: Matrix strategy testing (needs build)
+   - `deploy`: Deployment job (needs both build and test-matrix)
+
+4. **Matrix Strategy**:
+   - Tests with multiple compilers (gcc, clang)
+   - Tests with multiple build types (Debug, Release)
+
+5. **Common Actions**:
+   - `actions/checkout@v3`
+   - `actions/upload-artifact@v3`
+
+6. **Conditional Execution**:
+   - Deploy job only runs on main branch
+
+## Testing with GithubWorkflowTool
+
+### Using CLI:
+```bash
+# Discover workflows in this directory
+./build/gwt workflows examples/
+
+# Run the example workflow
+./build/gwt run examples/ examples/example-workflow.yml
+
+# Run with QEMU backend
+./build/gwt run examples/ examples/example-workflow.yml --qemu
+```
+
+### Using GUI:
+1. Launch the GUI: `./build/gwt-gui`
+2. Click "Clone Repository" (or use File > Open for local directory)
+3. Select the examples directory
+4. Select the workflow from the list
+5. Choose backend (Container or QEMU)
+6. Click "Run Workflow"
--- a/examples/example-workflow.yml
+++ b/examples/example-workflow.yml
@@ -0,0 +1,72 @@
+name: Example CI Workflow
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+env:
+  BUILD_TYPE: Release
+
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Setup build environment
+        run: |
+          echo "Setting up build environment"
+          sudo apt-get update
+      
+      - name: Configure
+        run: |
+          echo "Configuring project"
+          cmake -B build -G Ninja
+      
+      - name: Build
+        run: |
+          echo "Building project"
+          cmake --build build
+      
+      - name: Test
+        run: |
+          echo "Running tests"
+          cd build && ctest
+      
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-artifacts
+          path: build/
+
+  test-matrix:
+    name: Test Matrix
+    runs-on: ubuntu-latest
+    needs: build
+    
+    strategy:
+      matrix:
+        compiler: [gcc, clang]
+        build_type: [Debug, Release]
+    
+    steps:
+      - name: Test ${{ matrix.compiler }} - ${{ matrix.build_type }}
+        run: |
+          echo "Testing with ${{ matrix.compiler }} in ${{ matrix.build_type }} mode"
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: [build, test-matrix]
+    if: github.ref == 'refs/heads/main'
+    
+    steps:
+      - name: Deploy application
+        run: |
+          echo "Deploying application"
--- a/src/backends/QemuBackend.cpp
+++ b/src/backends/QemuBackend.cpp
@@ -1,5 +1,6 @@
 #include "backends/QemuBackend.h"
 #include <QProcess>
+#include <QDateTime>
 #include <QDebug>

 namespace gwt {
--- a/src/core/ArtifactManager.cpp
+++ b/src/core/ArtifactManager.cpp
@@ -2,6 +2,7 @@
 #include "core/StorageProvider.h"
 #include <QDir>
 #include <QFile>
+#include <QFileInfo>
 #include <QDebug>

 namespace gwt {
--- a/src/core/RepoManager.cpp
+++ b/src/core/RepoManager.cpp
@@ -2,6 +2,7 @@
 #include "core/StorageProvider.h"
 #include <QProcess>
 #include <QDir>
+#include <QFileInfo>
 #include <QDebug>

 namespace gwt {
--- a/src/core/StorageProvider.cpp
+++ b/src/core/StorageProvider.cpp
@@ -2,6 +2,8 @@
 #include <QStandardPaths>
 #include <QCryptographicHash>
 #include <QUrl>
+#include <QDir>
+#include <QFileInfo>
 #include <QDebug>

 namespace gwt {
--- a/src/gui/MainWindow.cpp
+++ b/src/gui/MainWindow.cpp
@@ -11,6 +11,7 @@
 #include <QInputDialog>
 #include <QMessageBox>
 #include <QLabel>
+#include <QFileInfo>

 namespace gwt {
 namespace gui {