gh-workflow
Trigger and monitor GitHub Actions workflows, CI/CD pipelines, and automated builds. Use when running workflows, triggering CI, deploying via GitHub Actions, downloading artifacts, or checking workflow status on github.com
When & Why to Use This Skill
The gh-workflow skill empowers developers to trigger, monitor, and manage GitHub Actions workflows and CI/CD pipelines directly through Claude. It streamlines the software delivery lifecycle by automating workflow execution, verifying git synchronization, and handling build artifacts, effectively bridging the gap between code development and automated deployment.
Use Cases
- Triggering manual production deployments or staging releases using workflow_dispatch with specific input parameters.
- Monitoring real-time CI/CD pipeline status and watching build progress to quickly identify and debug failures.
- Automating 'pre-flight' checks to ensure local commits are pushed to the remote repository before initiating a workflow run.
- Downloading and inspecting build artifacts, such as compiled binaries or test reports, to verify the integrity of workflow outputs.
- Optimizing development cycles by selecting specific matrix build cells and faster runner types (e.g., x64 over arm64) for rapid iteration and testing.
| name | gh-workflow |
|---|---|
| description | Trigger and monitor GitHub Actions workflows, CI/CD pipelines, and automated builds. Use when running workflows, triggering CI, deploying via GitHub Actions, downloading artifacts, or checking workflow status on github.com |
gh-workflow
Run GitHub workflows on github.com
Workflow
When the user asks to run a workflow:
- Verify git remotes and confirm commits are pushed (MANDATORY):
- Check remotes:
git remote -v | grep github.com - Get current commit:
git rev-parse HEAD - Verify commit exists on remote:
git fetch github && git branch -r --contains $(git rev-parse HEAD) | grep -q github/ - If not found, push first:
git push github HEAD:main(or appropriate branch name) - Quick check:
git fetch github && git branch -r --contains HEAD | grep -q github/ || echo "WARNING: HEAD not pushed to github"
- Check remotes:
- Check the workflow file in
.github/workflows/to understand its trigger type and inputs - For
workflow_dispatchworkflows: trigger directly withgh workflow run - For
pushworkflows: push to the remote first, then the workflow runs automatically - Use appropriate parameters based on the workflow's input definitions
- For testing/iteration with matrix builds: prefer x64 over arm64 (faster provisioning)
- Download workflow artifacts to verify outputs
Usage
# List workflows
GH_HOST=github.com gh workflow list
# Run a workflow
GH_HOST=github.com gh workflow run <workflow-name>
# Run with inputs
GH_HOST=github.com gh workflow run <workflow-name> -f key=value
# View recent runs
GH_HOST=github.com gh run list --workflow=<workflow-name>
# Watch a run
GH_HOST=github.com gh run watch <run-id>
# Download artifacts from a run
GH_HOST=github.com gh run download <run-id>
Testing matrix builds
For workflows with matrix builds, test with the fastest variant first:
- Prefer x64 over arm64 (x64 runners provision faster)
- Prefer ubuntu over macos (faster startup)
- Use workflow inputs to target specific matrix cells if supported
Examples
# Run workflow_dispatch workflow with inputs
GH_HOST=github.com gh workflow run luajit.yml -f release_tag=2025.11.23 -f create_release=true
# Run workflow at specific commit (preferred - explicit and reproducible)
GH_HOST=github.com gh workflow run luajit.yml --ref $(git rev-parse HEAD)
# Or with explicit SHA
GH_HOST=github.com gh workflow run luajit.yml --ref abc1234
# Run without creating release (testing)
GH_HOST=github.com gh workflow run nvim.yml -f create_release=false
# Download artifacts from latest run
GH_HOST=github.com gh run list --workflow=luajit.yml --limit 1 --json databaseId --jq '.[0].databaseId' | xargs -I {} GH_HOST=github.com gh run download {}