Github Actions

GitHub Actions Management

Manage GitHub Actions workflows: list workflows, view runs, trigger dispatches, view logs, and cancel runs.

Prerequisites

Requires authenticated gh CLI and jq. Use the unified gh-actions-tool script for all operations.

Quick Reference

gh-actions-tool auth                         # Verify auth & show detected repo
gh-actions-tool list                         # List all workflows
gh-actions-tool details <workflow>           # Show workflow details & inputs
gh-actions-tool runs [workflow]              # Show recent runs
gh-actions-tool running                      # Show in-progress runs
gh-actions-tool start <workflow> [opts]      # Trigger workflow_dispatch
gh-actions-tool logs <run-id> [--job name]   # View run logs
gh-actions-tool cancel <run-id>              # Cancel a run

Workflow

1. Confirm Repository Context (REQUIRED - First Command)

Before running any command, you MUST confirm the repository with the user:

gh-actions-tool auth

This shows the detected repository. Ask the user to confirm this is the correct repository before proceeding. Example:

"I detected the repository as owner/repo. Is this correct, or would you like me to use a different repository?"

Once confirmed, you do not need to ask again for the session.

If authentication fails, tell user to run:

gh auth login

If targeting a different repository, use --repo owner/repo on all commands.

2. Operations

List workflows:

gh-actions-tool list

View workflow details (shows triggers, inputs, jobs):

gh-actions-tool details "CI Build"
gh-actions-tool details deploy.yml

View run history:

gh-actions-tool runs                    # All runs
gh-actions-tool runs "Deploy"           # Filter by workflow
gh-actions-tool runs --limit 20         # More results

Check running workflows:

gh-actions-tool running

Trigger a workflow:

Before triggering, ask the user their preference:

"Would you like to provide inputs via command-line flags (--input KEY=VALUE) or use interactive mode where I'll prompt you for each input?"

Flag mode:

gh-actions-tool start "Deploy" --ref main
gh-actions-tool start "Deploy" --input environment=prod --input version=1.2.3

Interactive mode:

gh-actions-tool start "Deploy" --interactive

View logs:

gh-actions-tool logs 12345678                    # All logs
gh-actions-tool logs 12345678 --list-jobs        # List available jobs first
gh-actions-tool logs 12345678 --job "build"      # Specific job only

When viewing logs, first run with --list-jobs to show available jobs, then ask the user if they want all logs or a specific job.

Cancel a run:

gh-actions-tool cancel 12345678

Error Handling

Run Statuses

Important Notes

• Always confirm the repository on first use in a session
• For start command: Ask user preference for input method (flags vs interactive)
• For logs command: List jobs first, then ask which job's logs to show
• Use --repo owner/repo to override auto-detected repository