From eb992af85978a74cb7bf89c4b01e53fca504c993 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Dec 2025 03:06:06 +0000 Subject: [PATCH] Add documentation, examples, and fix missing includes Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- .github/workflows/ci.yml | 41 +++++ USAGE.md | 321 ++++++++++++++++++++++++++++++++++ examples/README.md | 53 ++++++ examples/example-workflow.yml | 72 ++++++++ src/backends/QemuBackend.cpp | 1 + src/core/ArtifactManager.cpp | 1 + src/core/RepoManager.cpp | 1 + src/core/StorageProvider.cpp | 2 + src/gui/MainWindow.cpp | 1 + 9 files changed, 493 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 USAGE.md create mode 100644 examples/README.md create mode 100644 examples/example-workflow.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b80f188 --- /dev/null +++ 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' || '' }} diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..7e710ab --- /dev/null +++ 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 diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..6ff5478 --- /dev/null +++ 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" diff --git a/examples/example-workflow.yml b/examples/example-workflow.yml new file mode 100644 index 0000000..59abdf8 --- /dev/null +++ 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" diff --git a/src/backends/QemuBackend.cpp b/src/backends/QemuBackend.cpp index 5c45223..ca52a7e 100644 --- a/src/backends/QemuBackend.cpp +++ b/src/backends/QemuBackend.cpp @@ -1,5 +1,6 @@ #include "backends/QemuBackend.h" #include +#include #include namespace gwt { diff --git a/src/core/ArtifactManager.cpp b/src/core/ArtifactManager.cpp index c92643c..c4b31b8 100644 --- a/src/core/ArtifactManager.cpp +++ b/src/core/ArtifactManager.cpp @@ -2,6 +2,7 @@ #include "core/StorageProvider.h" #include #include +#include #include namespace gwt { diff --git a/src/core/RepoManager.cpp b/src/core/RepoManager.cpp index a01b28d..2896c07 100644 --- a/src/core/RepoManager.cpp +++ b/src/core/RepoManager.cpp @@ -2,6 +2,7 @@ #include "core/StorageProvider.h" #include #include +#include #include namespace gwt { diff --git a/src/core/StorageProvider.cpp b/src/core/StorageProvider.cpp index 553669b..a94ccc6 100644 --- a/src/core/StorageProvider.cpp +++ b/src/core/StorageProvider.cpp @@ -2,6 +2,8 @@ #include #include #include +#include +#include #include namespace gwt { diff --git a/src/gui/MainWindow.cpp b/src/gui/MainWindow.cpp index ebbbcc9..dba5206 100644 --- a/src/gui/MainWindow.cpp +++ b/src/gui/MainWindow.cpp @@ -11,6 +11,7 @@ #include #include #include +#include namespace gwt { namespace gui {