gh-workflows

name	gh-workflows
description	Manage GitHub Actions workflows with the gh CLI (list, run, cancel, monitor).

When to Use

Use this skill whenever you need to inspect, trigger, or stop GitHub Actions workflows. It wraps gh workflow and gh run commands so you can keep CI pipelines healthy without leaving the terminal.

Prerequisites

1. gh CLI authenticated with gh auth login --scopes repo,workflow. Confirm via gh auth status.
2. jq available to pretty-print JSON results.
3. Environment:
   • GITHUB_REPOSITORY (owner/name). Ask for it if missing.
   • GITHUB_TOKEN (gh uses it automatically once authenticated).
   • DEFAULT_BRANCH (fallback for manual dispatches; default to main).

Common Parameters

• --repo "$GITHUB_REPOSITORY" is required for every command.
• --json ... --jq '.' returns machine-friendly payloads.
• When scripts provide workflow names, accept either filename (deploy.yml) or workflow ID.

Procedures

List Workflows (/workflows-list)

1. Run: gh workflow list --repo "$GITHUB_REPOSITORY" --limit ${LIMIT:-20} --json id,name,path,state.
2. Use jq to format the response.
3. Summarize key fields: name, path, state, and id so downstream commands can use them.

List Workflow Runs (/workflows-runs)

1. Require a workflow identifier.
2. Optional filters:
   • Branch: --branch ${BRANCH} (omit if empty).
   • Status: --status ${STATUS:-all}.
3. Command:

   gh run list --repo "$GITHUB_REPOSITORY" \
     --workflow "$WORKFLOW" \
     ${BRANCH:+--branch "$BRANCH"} \
     --status ${STATUS:-all} \
     --limit ${LIMIT:-20} \
     --json databaseId,workflowName,displayTitle,headBranch,status,conclusion,createdAt
   

4. Pipe to jq '.' and surface the most recent run id for convenience.

View a Workflow Run (/workflows-view)

1. Accept a run_id (numeric or URL) and optional --log flag.
2. Command:

   gh run view "$RUN_ID" --repo "$GITHUB_REPOSITORY" \
     --json databaseId,workflowName,displayTitle,event,headBranch,status,conclusion,logsUrl,htmlUrl
   

3. Share the JSON and hyperlink to logsUrl/htmlUrl for quick navigation.

Cancel a Run (/workflows-cancel)

1. Confirm the run is in in_progress or queued state (use gh run view).
2. Command sequence:

   gh run cancel "$RUN_ID" --repo "$GITHUB_REPOSITORY"
   gh run watch "$RUN_ID" --repo "$GITHUB_REPOSITORY" --exit-status || true
   

3. Report the final status (cancelled/completed). If already finished, note that cancellation was skipped.

Trigger a Workflow (/workflows-trigger)

1. Require workflow file/ID plus ref/branch.
2. Compose inputs:

   EXTRA_INPUTS=${INPUTS_JSON:+--inputs "$INPUTS_JSON"}
   gh workflow run "$WORKFLOW" --repo "$GITHUB_REPOSITORY" --ref "${REF:-${BRANCH:-$DEFAULT_BRANCH}}" $EXTRA_INPUTS
   

3. Capture the run id from gh output and share it for monitoring.

Monitor a Run (/workflows-monitor)

1. Command: gh run watch "$RUN_ID" --repo "$GITHUB_REPOSITORY" --exit-status.
2. Stream output back. At completion, annotate whether the run concluded with success, failure, or cancellation.

Safety Checks

• Never cancel or rerun workflows outside the configured repo.
• If a command fails due to missing repo/ref, prompt the user for the missing data before retrying.
• Treat manual dispatch inputs carefully—validate JSON before passing --inputs.