gh-local

The gh-local skill provides a robust environment for developers to execute and debug GitHub Actions CI workflows directly on their local machine. By leveraging the nektos/act framework inside a Docker container, it allows you to simulate the exact CI environment that GitHub would normally host, significantly reducing the feedback loop when iterating on complex workflow files or troubleshooting elusive CI failures. This tool is ideal for software engineers working with CI/CD pipelines who need to ensure that YAML configurations, environment variables, and shell scripts function as expected before committing code.

• Executes specific jobs or full workflow suites using the catthehacker/ubuntu:act-latest image for high compatibility with standard GitHub-hosted runners.

• Supports configuration of local test environments, ensuring consistency on Apple Silicon and other architectures via --container-architecture flags.

• Provides real-time progress monitoring and automated log tailing, reporting step-by-step outcomes like npm installations, build phases, and test executions directly to your session.

• Enables deep inspection of error outputs when workflows fail, allowing you to modify and re-test configurations locally within minutes.

• Verify that Docker Desktop and the act CLI are installed and active before execution; installation guidance is provided if dependencies are missing.

• Note that while act simulates most actions, it does not support native GitHub artifact uploads; these steps may fail or be skipped by design.

• Always specify the target job or workflow file to optimize execution time; if unspecified, the agent defaults to .github/workflows/ci.yml.

• The tool respects environment variables defined in your workflow YAML, allowing for seamless parity between local and remote environments.

• Use this skill to identify script errors, missing dependencies, or pathing issues in your CI pipeline without wasting GitHub runner minutes or polluting your commit history with trial-and-error fixes.