GithubWorkflowTool/LIMITATIONS.md

Known Limitations & Resolution Strategy (v1)

1. Scope

This document formally defines acknowledged limitations of GithubWorkflowTool v1, explains why they exist, and documents the intended resolution path for future versions.

The goal is transparency, predictability, and a clear upgrade trajectory rather than silent incompatibility.

---

2. Limitation Categories

Limitations are grouped by capability class and assigned a resolution tier:

• Deferred – intentionally excluded from v1, planned for v2+
• Constrained – partially supported with explicit restrictions
• External – blocked by legal, platform, or ecosystem constraints
• Configurable – disabled or limited by default but unlockable

---

3. Detailed Limitations

3.1 Incomplete GitHub Actions Feature Coverage

Status

• Type: Deferred
• Severity: Medium
• Impact: Some workflows may fail or require modification

Description

GithubWorkflowTool v1 implements a subset of GitHub Actions semantics. Unsupported or partially supported features include (non-exhaustive):

• Advanced expressions (fromJSON, hashFiles, complex boolean chains)
• Reusable workflows (workflow_call)
• Dynamic job generation outside strategy.matrix
• Job-level permissions and token scoping
• Environments with approval gates
• Concurrency groups

Rationale

GitHub Actions is not formally specified; it is an evolving behavior-driven platform. v1 prioritizes deterministic local execution over speculative compatibility.

Resolution Path

• v2: Expand expression engine coverage
• v2: Add reusable workflow resolution
• v3: Permissions & environment gates (read-only simulation)

User Guidance (v1)

• Prefer explicit run: steps over deeply nested expressions
• Avoid reusable workflows unless flattened
• Use matrix strategies only for static axes

---

3.2 Third-Party Actions Compatibility

Status

• Type: Constrained
• Severity: Medium–High
• Impact: Some marketplace actions may fail

Description

Some third-party actions assume:

• Preinstalled tools on GitHub-hosted runners
• Full Node.js runtime availability
• Docker-in-Docker capability
• Privileged filesystem or network access

v1 does not guarantee these assumptions unless explicitly provided by the selected runner backend.

Supported Action Types (v1)

• Local composite actions
• Docker-based actions
• Node-based actions only if:
  • Container backend is used, or
  • Required runtimes are present in the VM template

Resolution Path

• v2: Action capability probing (pre-flight validation)
• v2: Curated "known-good" action compatibility list
• v3: Optional toolchain auto-provisioning

User Guidance (v1)

• Prefer Docker-based actions
• Pin action versions explicitly
• Use container backend when testing marketplace actions

---

3.3 Service Containers Not Implemented

Status

• Type: Deferred
• Severity: High (for integration-heavy workflows)
• Impact: DB-backed or multi-service workflows will fail

Description

GitHub Actions services: (e.g., PostgreSQL, Redis) are not supported in v1.

There is no orchestration layer for:

• Service lifecycle management
• Network aliasing
• Health checks
• Port mapping into jobs

Rationale

Service containers introduce orchestration complexity comparable to a lightweight Kubernetes layer. This is intentionally excluded from v1 to keep execution semantics simple and debuggable.

Resolution Path

• v2: Container-backend-only service support
• v2.1: Declarative service lifecycle
• v3: QEMU backend service networking

User Guidance (v1)

Replace services with:

• External services (run manually, point workflows at fixed endpoints)
• Embedded test doubles
• Single-container workflows
• Manual database/service setup before workflow execution

Example Workaround:

Instead of:

jobs:
  test:
    services:
      postgres:
        image: postgres:14

Use:

# Run service manually
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:14

# Then run workflow
gwt run /path/to/repo /path/to/workflow.yml --env DATABASE_URL=postgresql://localhost:5432

---

3.4 macOS Runner Images Unsupported

Status

• Type: External
• Severity: High (for Apple-specific projects)
• Impact: macOS workflows cannot be executed

Description

macOS GitHub-hosted runners are not supported in v1.

Reasons:

• Apple licensing restrictions
• Virtualization limitations outside Apple hardware
• Lack of redistributable macOS base images

Resolution Path

• v2: "macOS-host-like" profile (best-effort simulation on Linux)
• v3: Native macOS-host execution (host-only, no VM)
• No QEMU-based macOS support planned (licensing constraints)

User Guidance (v1)

• Use Linux runners for cross-platform builds where possible
• Split workflows:
  • Linux CI locally (with GithubWorkflowTool)
  • macOS CI only on GitHub
• For macOS-specific testing: use GitHub Actions cloud runners

---

3.5 Limited Network Access in Runners

Status

• Type: Configurable
• Severity: Medium
• Impact: Actions requiring external downloads may fail

Description

Network access inside runners may be:

• Restricted
• Rate-limited
• Disabled entirely (offline mode)

This applies especially to:

• QEMU backend
• Reproducibility-focused runs
• CI debugging scenarios

Rationale

Unrestricted network access:

• Breaks reproducibility
• Introduces nondeterministic failures
• Can leak secrets unintentionally

Resolution Path

• v1.1: Domain allowlist support
• v2: Network profiles per runner
• v2: Cached dependency mirrors
• v3: Deterministic fetch recording & replay

User Guidance (v1)

• Vendor dependencies where possible
• Use local mirrors or caches
• Enable network explicitly when required (container mode allows network by default)
• For offline testing, pre-download all dependencies

---

4. Limitation Visibility & UX Requirements

CLI Requirements

The gwt doctor command must report:

• Unsupported workflow features detected in a workflow file
• Action incompatibilities
• Missing toolchains (Docker, Podman, QEMU)
• Runner backend availability
• Clear warnings before execution, not after failure

Example Output:

$ gwt doctor /path/to/repo/.github/workflows/ci.yml

GithubWorkflowTool Diagnostics
==============================

Workflow: ci.yml
✓ Basic workflow structure valid
✓ Job dependencies resolvable
⚠ Warning: Uses reusable workflow (not supported in v1)
⚠ Warning: Service container 'postgres' detected (not supported in v1)
  → Workaround: Run PostgreSQL manually before workflow execution
✗ Error: Uses 'hashFiles' expression (not supported in v1)
  → Resolution: Simplify expression or upgrade to v2 (planned)

Backend Availability:
✓ Container backend: Docker detected (v24.0.0)
✓ QEMU backend: Available (v7.2.0)

Recommendation: 3 issues detected, 2 warnings, 1 error
Workflow may fail or require modifications to run successfully.

GUI Requirements

Visual badges on workflows/jobs:

• "✓ Fully Supported"
• "⚠ Partially Supported" (with details in hover/tooltip)
• "✗ Unsupported in v1" (with workaround in detail pane)
• "Requires Container Backend"
• "Requires QEMU Backend"

When hovering over a badge or clicking for details, explain:

• What limitation applies
• Why it exists
• Recommended workaround
• Expected version for full support

---

5. Versioning & Compatibility Policy

v1.x

• No breaking behavior changes
• Limitations remain explicit and documented
• New features may be added if backward compatible
• Unsupported features fail fast with clear error messages

v2.0

• Feature expansion allowed
• Backward compatibility preferred but not guaranteed
• Migration guide provided for breaking changes
• Unsupported features must fail fast, not silently degrade

Future Versions

• Incremental improvements to limitation resolution
• Regular compatibility matrix updates
• Community feedback integration

---

6. Acceptance Criteria (Limitations Spec)

This specification is satisfied when:

1. ✅ All listed limitations are explicitly detected or documented at runtime
2. ✅ Failures caused by limitations produce actionable diagnostics
3. ✅ Users can predict before execution whether a workflow is likely to succeed
4. ✅ Resolution paths are versioned and traceable
5. ✅ Documentation is accessible and linked from main README

---

7. Compatibility Matrix (Preview)

A detailed compatibility matrix mapping common GitHub Actions to backend support will be provided in a future specification. Preview:

Action	Container	QEMU	Status	Notes
actions/checkout@v3	✓	✓	Full	Git must be available
actions/cache@v3	⚠	⚠	Partial	Local cache only
actions/setup-node@v3	✓	✓	Full	Node must be in image
docker/build-push-action@v4	✓	✗	Container only	DinD required
Service containers	✗	✗	Not supported	v2 planned
Reusable workflows	✗	✗	Not supported	v2 planned

Full matrix to be documented in COMPATIBILITY_MATRIX.md (future work).

---

8. Feedback and Contributions

Users encountering limitations not documented here should:

1. Check for existing GitHub issues
2. Report new limitations with:
   • Workflow file (or minimal example)
   • Error message
   • Expected behavior
   • Actual behavior
3. Contribute workarounds to documentation

---

Summary

GithubWorkflowTool v1 is designed with intentional constraints to ensure:

• Predictable, deterministic execution
• Clear error messages and diagnostics
• Transparent limitations with documented workarounds
• Traceable resolution path for future versions

Users should consult this document and use the gwt doctor command before deploying workflows to understand compatibility and required modifications.

For questions or issues, please refer to the GitHub repository issue tracker.