Cli Gh

GitHub CLI (gh)

Overview

Expert guidance for GitHub CLI (gh) operations and workflows. Use this skill for command-line GitHub operations including pull request management, issue tracking, repository operations, workflow automation, and codespace management.

Key capabilities:

• Create and manage pull requests from the terminal
• Track and organize issues efficiently
• Search across all of GitHub (repos, issues, PRs)
• Manage labels and project organization
• Trigger and monitor GitHub Actions workflows
• Work with codespaces
• Automate repository operations and releases

Safety Rules

CRITICAL: This skill NEVER uses destructive gh CLI operations.

This skill focuses exclusively on safe, read-only, or reversible GitHub operations. The following commands are PROHIBITED and must NEVER be used:

Permanently destructive commands:

• gh repo delete - Repository deletion
• gh repo archive - Repository archival
• gh release delete - Release deletion
• gh release delete-asset - Asset deletion
• gh run delete - Workflow run deletion
• gh cache delete - Cache deletion
• gh secret delete - Secret deletion
• gh variable delete - Variable deletion
• gh label delete - Label deletion
• gh ssh-key delete - SSH key deletion (can lock out users)
• gh gpg-key delete - GPG key deletion
• gh codespace delete - Codespace deletion
• gh extension remove - Extension removal
• gh gist delete - Gist deletion
• Bulk deletion operations using xargs with any destructive commands
• Shell commands: rm -rf (except for temporary file cleanup)

Allowed operations:

• Creating resources (PRs, issues, releases, labels, repos)
• Viewing and listing (status, logs, information, searches)
• Updating and editing existing resources
• Closing PRs/issues (reversible - can be reopened)
• Canceling workflow runs (stops execution without deleting data)
• Merging pull requests (after proper review)
• Read-only git operations (git status, git log, git diff)

Installation & Setup

# Login to GitHub
gh auth login

# Check authentication status
gh auth status

# Configure git to use gh as credential helper
gh auth setup-git

Pull Requests

Creating PRs

# Create PR interactively
gh pr create

# Create PR with title and body
gh pr create --title "Add feature" --body "Description"

# Create PR to specific branch
gh pr create --base main --head feature-branch

# Create draft PR
gh pr create --draft

# Create PR from current branch
gh pr create --fill  # Uses commit messages

Viewing PRs

# List PRs
gh pr list

# List my PRs
gh pr list --author @me

# View PR details
gh pr view 123

# View PR in browser
gh pr view 123 --web

# View PR diff
gh pr diff 123

# Check PR status
gh pr status

Managing PRs

# Checkout PR locally
gh pr checkout 123

# Review PR
gh pr review 123 --approve
gh pr review 123 --comment --body "Looks good!"
gh pr review 123 --request-changes --body "Please fix X"

# Merge PR
gh pr merge 123
gh pr merge 123 --squash
gh pr merge 123 --rebase
gh pr merge 123 --merge

# Close PR
gh pr close 123

# Reopen PR
gh pr reopen 123

# Ready draft PR
gh pr ready 123

# Update PR branch with base branch
gh pr update-branch 123

PR Checks

# View PR checks
gh pr checks 123

# Watch PR checks
gh pr checks 123 --watch

Issues

Creating Issues

# Create issue interactively
gh issue create

# Create issue with title and body
gh issue create --title "Bug report" --body "Description"

# Create issue with labels
gh issue create --title "Bug" --label bug,critical

# Assign issue
gh issue create --title "Task" --assignee @me

Viewing Issues

# List issues
gh issue list

# List my issues
gh issue list --assignee @me

# List by label
gh issue list --label bug

# View issue details
gh issue view 456

# View in browser
gh issue view 456 --web

Managing Issues

# Close issue
gh issue close 456

# Reopen issue
gh issue reopen 456

# Edit issue
gh issue edit 456 --title "New title"
gh issue edit 456 --add-label bug
gh issue edit 456 --add-assignee @user

# Comment on issue
gh issue comment 456 --body "Update"

# Create branch to work on issue
gh issue develop 456 --checkout

Repository Operations

Repository Info

# View repository
gh repo view

# View in browser
gh repo view --web

# Clone repository
gh repo clone owner/repo

# Fork repository
gh repo fork owner/repo

# List repositories
gh repo list owner

Repository Management

# Create repository
gh repo create my-repo --public
gh repo create my-repo --private

# Sync fork
gh repo sync owner/repo

# Set default repository
gh repo set-default

Search

Search across all of GitHub for repositories, issues, and pull requests.

Search Repositories

# Search for repositories
gh search repos "machine learning" --language=python

# Search with filters
gh search repos --stars=">1000" --topic=kubernetes

Search Issues

# Search issues across GitHub
gh search issues "bug" --label=critical --state=open

# Exclude results (note the -- to prevent flag interpretation)
gh search issues -- "memory leak -label:wontfix"

Search Pull Requests

# Search PRs
gh search prs --author=@me --state=open

# Search with date filters
gh search prs "refactor" --created=">2024-01-01"

Labels

Manage repository labels for issue and PR organization.

List and View Labels

# List all labels in repository
gh label list

Create and Edit Labels

# Create new label
gh label create "priority: high" --color FF0000 --description "High priority items"

# Edit existing label
gh label edit "bug" --color FFAA00 --description "Something isn't working"

Clone Labels Between Repos

# Clone labels from another repository
gh label clone owner/source-repo

Codespaces

Manage GitHub Codespaces directly from the terminal.

List and Create Codespaces

# List codespaces
gh codespace list

# Create new codespace
gh codespace create --repo owner/repo

Connect to Codespaces

# SSH into codespace
gh codespace ssh

# Open in VS Code
gh codespace code

# Open in JupyterLab
gh codespace jupyter

Manage Codespace Files

# Copy files to/from codespace
gh codespace cp local-file.txt remote:~/path/
gh codespace cp remote:~/path/file.txt ./local-dir/

# View logs
gh codespace logs

Releases

Creating Releases

# Create release
gh release create v1.0.0

# Create release with notes
gh release create v1.0.0 --notes "Release notes"

# Create release with files
gh release create v1.0.0 dist/*.tar.gz

# Create draft release
gh release create v1.0.0 --draft

# Generate release notes automatically
gh release create v1.0.0 --generate-notes

Managing Releases

# List releases
gh release list

# View release
gh release view v1.0.0

# Download release assets
gh release download v1.0.0

Gists

# Create gist
gh gist create file.txt

# Create gist from stdin
echo "content" | gh gist create -

# List gists
gh gist list

# View gist
gh gist view <gist-id>

# Edit gist
gh gist edit <gist-id>

Configuration

# Set default editor
gh config set editor vim

# Set default git protocol
gh config set git_protocol ssh

# View configuration
gh config list

# Set browser
gh config set browser firefox

Quick Reference

Common gh operations at a glance:

Additional Resources

Reference Guides

For detailed patterns and advanced usage, see:

• [Workflows & Actions](references/workflows-actions.md) - GitHub Actions workflows, runs, cache management, and CI/CD integration patterns
• [Advanced Features](references/advanced-features.md) - Aliases, API access, extensions, secrets, SSH/GPG keys, organizations, projects, and advanced scripting
• [Automation Workflows](references/automation-workflows.md) - Common automation patterns, daily reports, release automation, and team collaboration workflows
• [Troubleshooting](references/troubleshooting.md) - Solutions for authentication, permissions, rate limiting, and common errors

Example Scripts

Practical automation scripts (see examples/ directory):

• auto-pr-create.sh - Automated PR creation workflow
• issue-triage.sh - Bulk issue labeling and assignment
• workflow-monitor.sh - Watch and notify on workflow completion
• release-automation.sh - Complete release workflow automation

External Documentation

• Official Manual: https://cli.github.com/manual
• GitHub Community: https://github.com/cli/cli/discussions
• API Documentation: https://docs.github.com/en/rest
• Extension Marketplace: https://github.com/topics/gh-extension

JSON Output

Use --json flag for structured output. Always verify field names with `--help` as they differ from GitHub API names.

# Check available JSON fields for any command
gh repo view --help | grep -A 50 "JSON FIELDS"
gh pr list --help | grep -A 50 "JSON FIELDS"

Common JSON Field Corrections

Repository View Fields

# Common fields for gh repo view --json
gh repo view owner/repo --json name,description,stargazerCount,forkCount,updatedAt,url,readme

Tips

1. Use --web flag to open items in browser for detailed view 2. Leverage interactive prompts by omitting parameters - most commands support interactive mode 3. Apply filters with --author, --label, --state to narrow down lists efficiently 4. Add --json flag to enable scriptable output for automation 5. Always check `--help` for valid JSON field names - they differ from GitHub API 6. Use gh repo create --template to scaffold from template repositories 7. Enable auto-merge with gh pr merge --auto for PRs that pass checks

Advanced Features

Advanced gh CLI capabilities for power users and automation.

Aliases

Create custom shortcuts for frequently used commands.

# Create alias
gh alias set pv "pr view"
gh alias set bugs "issue list --label bug"

# List aliases
gh alias list

# Use alias
gh pv 123

API Access

Direct access to GitHub's REST API through gh CLI.

# Make API call
gh api repos/:owner/:repo/issues

# With JSON data
gh api repos/:owner/:repo/issues -f title="Bug" -f body="Description"

# Paginated results
gh api --paginate repos/:owner/:repo/issues

Extensions

Extend gh CLI functionality with community extensions.

# List extensions
gh extension list

# Install extension
gh extension install owner/gh-extension

# Upgrade extensions
gh extension upgrade --all

Secrets and Variables

Manage GitHub Actions secrets and variables.

Secrets

# List secrets
gh secret list

# Set secret
gh secret set SECRET_NAME

# Set secret from file
gh secret set SECRET_NAME < secret.txt

Variables

# List variables
gh variable list

# Set variable
gh variable set VAR_NAME --body "value"

SSH and GPG Keys

SSH Keys

# List SSH keys
gh ssh-key list

# Add SSH key
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"

GPG Keys

# List GPG keys
gh gpg-key list

# Add GPG key
gh gpg-key add <key-file>

Organizations

Manage organization settings and resources.

# List organizations
gh org list

# View organization info
gh org view <org-name>

Projects

Work with GitHub Projects (beta).

# List projects
gh project list --owner <org-name>

# View project
gh project view <project-number>

# Create project
gh project create --owner <org-name> --title "Project Name"

Repository Rulesets

View information about repository rulesets.

# List rulesets
gh ruleset list

# View ruleset
gh ruleset view <ruleset-id>

Attestations

Work with artifact attestations for supply chain security.

# Verify release attestation
gh release verify <tag>

# Verify specific asset
gh release verify-asset <file> --repo owner/repo

Advanced Scripting Patterns

Using jq with gh

# Extract specific fields from JSON output
gh pr list --json number,title,author --jq '.[] | select(.author.login=="username")'

# Count open PRs
gh pr list --json state --jq 'length'

# Get PR numbers only
gh pr list --json number --jq '.[].number'

Error Handling in Scripts

# Check if PR exists before operating
if gh pr view 123 &>/dev/null; then
  gh pr merge 123
else
  echo "PR not found"
fi

Batch Operations

# Add label to multiple issues
gh issue list --assignee @me --json number --jq '.[].number' | xargs -I {} gh issue edit {} --add-label "in-progress"

Automation Workflows

Common workflow patterns and automation examples using gh CLI.

Common Workflows

Code Review Workflow

# List PRs assigned to you
gh pr list --assignee @me

# Checkout PR for testing
gh pr checkout 123

# Run tests, review code...

# Approve PR
gh pr review 123 --approve --body "LGTM!"

# Merge PR
gh pr merge 123 --squash

Quick PR Creation

# Create feature branch, make changes, commit
git checkout -b feature/new-feature
# ... make changes ...
git add .
git commit -m "Add new feature"
git push -u origin feature/new-feature

# Create PR from commits
gh pr create --fill

# View PR
gh pr view --web

Issue Triage

# List open issues
gh issue list

# Add labels to issues
gh issue edit 456 --add-label needs-triage
gh issue edit 456 --add-label bug

# Assign issue
gh issue edit 456 --add-assignee @developer

Advanced Automation Patterns

Daily Standup Report

#!/bin/bash
# Generate daily activity report

echo "## My GitHub Activity - $(date +%Y-%m-%d)"
echo ""
echo "### PRs Created"
gh pr list --author @me --search "created:$(date +%Y-%m-%d)"
echo ""
echo "### PRs Reviewed"
gh search prs "reviewed-by:@me created:$(date +%Y-%m-%d)"
echo ""
echo "### Issues Closed"
gh issue list --author @me --state closed --search "closed:$(date +%Y-%m-%d)"

Auto-label PRs by Files Changed

#!/bin/bash
# Auto-label PR based on changed files

PR_NUMBER=$1
FILES=$(gh pr diff $PR_NUMBER --name-only)

if echo "$FILES" | grep -q "^docs/"; then
  gh pr edit $PR_NUMBER --add-label "documentation"
fi

if echo "$FILES" | grep -q "\.test\."; then
  gh pr edit $PR_NUMBER --add-label "tests"
fi

if echo "$FILES" | grep -q "package\.json"; then
  gh pr edit $PR_NUMBER --add-label "dependencies"
fi

Sync Fork with Upstream

#!/bin/bash
# Keep fork in sync with upstream

gh repo sync owner/fork --source upstream/repo --branch main
git fetch origin main
git merge origin/main

Release Checklist Automation

#!/bin/bash
# Automated release checklist

VERSION=$1

# 1. Ensure on main branch
git checkout main && git pull

# 2. Run tests
npm test || exit 1

# 3. Create release tag
git tag -a "v$VERSION" -m "Release $VERSION"
git push origin "v$VERSION"

# 4. Create GitHub release
gh release create "v$VERSION" --generate-notes

# 5. Upload artifacts
gh release upload "v$VERSION" dist/*

Bulk PR Operations

#!/bin/bash
# Approve all PRs from dependabot

gh pr list --author app/dependabot --json number --jq '.[].number' | \
  xargs -I {} gh pr review {} --approve --body "Auto-approved dependency update"

Monitor CI Status

#!/bin/bash
# Monitor all active PRs for CI failures

gh pr list --json number,title,statusCheckRollup --jq '.[] |
  select(.statusCheckRollup.state == "FAILURE") |
  "\(.number): \(.title)"'

Notifications and Monitoring

Watch for PR Reviews

# Monitor PR for new reviews
while true; do
  REVIEWS=$(gh pr view 123 --json reviews --jq '.reviews | length')
  echo "Reviews: $REVIEWS"
  sleep 60
done

Get Notified on Workflow Completion

#!/bin/bash
# Wait for workflow and send notification

RUN_ID=$1
gh run watch $RUN_ID
STATUS=$(gh run view $RUN_ID --json conclusion --jq '.conclusion')

if [ "$STATUS" = "success" ]; then
  osascript -e 'display notification "Workflow passed!" with title "GitHub Actions"'
else
  osascript -e 'display notification "Workflow failed!" with title "GitHub Actions"'
fi

PR Staleness Check

#!/bin/bash
# Find stale PRs (no activity in 30 days)

gh pr list --json number,title,updatedAt --jq '.[] |
  select((now - (.updatedAt | fromdateiso8601)) > (30*86400)) |
  "\(.number): \(.title)"'

Team Collaboration Patterns

Assign PR Reviewers by Team

# Auto-assign team members as reviewers
gh pr create --reviewer team/backend,team/security --assignee @me

Bulk Issue Assignment

# Assign all bugs to triage team
gh issue list --label bug --json number --jq '.[].number' | \
  xargs -I {} gh issue edit {} --add-assignee @triager

Weekly Team Report

#!/bin/bash
# Generate weekly team activity summary

TEAM="myteam"
SINCE=$(date -v-7d +%Y-%m-%d)

echo "# Team Activity Report - Week of $(date +%Y-%m-%d)"
echo ""
echo "## PRs Merged"
gh search prs "team:$TEAM is:merged merged:>=$SINCE" --limit 100
echo ""
echo "## Issues Closed"
gh search issues "team:$TEAM is:closed closed:>=$SINCE" --limit 100

Repository Management

Batch Repository Creation

#!/bin/bash
# Create multiple repositories from template

TEMPLATE="org/template-repo"
REPOS=("project-a" "project-b" "project-c")

for repo in "${REPOS[@]}"; do
  gh repo create "org/$repo" --template "$TEMPLATE" --private
done

Clone All Organization Repos

#!/bin/bash
# Clone all repos from an organization

ORG="myorg"
gh repo list "$ORG" --limit 1000 --json name --jq '.[].name' | \
  xargs -I {} gh repo clone "$ORG/{}"

Sync Multiple Forks

#!/bin/bash
# Sync all your forks with upstream

gh repo list @me --fork --json name,parent --jq '.[] |
  "\(.name) \(.parent.owner.login)/\(.parent.name)"' | \
  while read fork upstream; do
    gh repo sync "$fork" --source "$upstream"
  done

Troubleshooting

Common issues and solutions when using gh CLI.

Authentication Issues

Not Authenticated

Error: gh: To get started with GitHub CLI, please run: gh auth login

Solution:

# Login with web browser
gh auth login

# Login with token
gh auth login --with-token < token.txt

# Check auth status
gh auth status

Token Expired

Error: HTTP 401: Bad credentials (HTTP 401)

Solution:

# Refresh authentication
gh auth refresh

# Re-login if refresh fails
gh auth logout
gh auth login

Wrong Account

Problem: Authenticated as wrong user

Solution:

# Check current authentication
gh auth status

# Switch accounts
gh auth login --hostname github.com

# Use multiple accounts with different hosts
export GH_HOST=github.com
gh auth login

Missing Scopes

Error: HTTP 403: Resource not accessible by personal access token

Solution:

# Add required scopes
gh auth refresh -h github.com -s repo,workflow,admin:org

# Common scopes needed:
# - repo: Full control of private repositories
# - workflow: Update GitHub Action workflows
# - admin:org: Full control of orgs and teams
# - write:packages: Upload packages to GitHub Package Registry

Permission Issues

Insufficient Permissions

Error: HTTP 403: Resource not accessible by personal access token

Solution:

• Ensure your token has required scopes (repo, workflow, admin:org, etc.)
• Re-run gh auth refresh -h github.com -s <scope> to add scopes
• Check if you're a member of the organization/repository

Repository Access Denied

Error: HTTP 404: Not Found (when repo exists)

Possible Causes:

1. Repository is private and you don't have access 2. Repository name is incorrect 3. You're authenticated with wrong account

Solution:

# Verify repository access
gh repo view owner/repo

# Check if you're using correct repo name
gh repo list owner --limit 100 | grep repo-name

# Verify authentication
gh auth status

Cannot Push to Repository

Error: Permission to owner/repo denied to user

Solution:

# Check if you have write access
gh api repos/owner/repo --jq '.permissions'

# Verify git remote uses correct authentication
gh auth setup-git

# Check remote URL
git remote -v

Rate Limiting

API Rate Limit Exceeded

Error: API rate limit exceeded for user

Solution:

# Check rate limit status
gh api rate_limit

# Use authenticated requests (higher limit: 5000/hr vs 60/hr)
gh auth login

# Wait for rate limit reset or use conditional requests
gh api rate_limit --jq '.rate.reset' | xargs -I {} date -r {}

Secondary Rate Limit

Error: You have exceeded a secondary rate limit

Solution:

• Slow down request rate
• Add delays between API calls
• Use --paginate carefully with large result sets

Common Command Errors

PR Already Exists

Error: pull request create failed: a pull request for branch "feature" into branch "main" already exists

Solution:

# Find existing PR
gh pr list --head feature

# Update existing PR instead
gh pr edit <number> --title "New title" --body "New description"

# Or checkout and update the branch
gh pr checkout <number>
git commit --amend
git push --force-with-lease

Cannot Merge PR

Error: GraphQL: Pull Request is not mergeable

Causes & Solutions:

• Merge conflicts:

  gh pr checkout <number>
  git merge main  # or base branch
  # Resolve conflicts
  git push

• Required checks failing:

  gh pr checks <number>  # View status
  # Wait for checks or fix failures

• Required reviews missing:

  gh pr view <number> --json reviewDecision
  # Get required approvals

• Branch protection:

  gh api repos/:owner/:repo/branches/main/protection
  # Ensure all rules are satisfied

Workflow Not Found

Error: could not resolve to a Workflow

Solution:

# List available workflows
gh workflow list

# Use exact workflow file name (not display name)
gh workflow run ci.yml  # not "CI" or "ci"

# Use workflow ID
gh api repos/:owner/:repo/actions/workflows --jq '.workflows[] | "\(.id): \(.name)"'
gh workflow run <workflow-id>

Cannot Checkout PR

Error: failed to check out PR: could not find a branch for this pull request

Solution:

# Fetch PR branch manually
gh pr view <number> --json headRefName,headRepository --jq '.headRefName'

# Checkout with fetch
git fetch origin pull/<number>/head:pr-<number>
git checkout pr-<number>

Issue/PR Not Found

Error: could not resolve to a PullRequest/Issue with the number of <number>

Solution:

# Verify you're in correct repository
gh repo view

# Set default repository
gh repo set-default owner/repo

# Specify repository explicitly
gh pr view <number> --repo owner/repo

Installation Issues

gh Command Not Found

Solutions:

# macOS with Homebrew
brew install gh

# Update Homebrew if gh is outdated
brew upgrade gh

# Update PATH (if installed but not in PATH)
export PATH="/usr/local/bin:$PATH"

# Verify installation
which gh
gh --version

Extension Installation Fails

Error: failed to install extension

Solution:

# Check extension name is correct
gh extension search <keyword>

# Install with full repository path
gh extension install owner/gh-extension-name

# Update existing extension
gh extension upgrade extension-name

# Reinstall if corrupted
gh extension remove extension-name
gh extension install owner/gh-extension-name

Upgrade Issues

Error: failed to upgrade gh

Solution:

# macOS
brew upgrade gh

# Check for conflicts
brew doctor

# Reinstall if needed
brew reinstall gh

Configuration Issues

Default Repository Not Set

Error: no default repository has been set

Solution:

# Set default repository interactively
gh repo set-default

# Set default repository explicitly
gh repo set-default owner/repo

# Or use --repo flag
gh pr list --repo owner/repo

Editor Not Opening

Problem: gh pr create doesn't open editor

Solution:

# Set default editor
gh config set editor vim
gh config set editor "code --wait"  # VS Code
gh config set editor "nano"

# Or use EDITOR environment variable
export EDITOR=vim

Git Protocol Issues

Error: Issues with SSH/HTTPS

Solution:

# Set preferred protocol
gh config set git_protocol https
# or
gh config set git_protocol ssh

# Setup git credentials
gh auth setup-git

Debugging Tips

Enable Verbose Output

# Debug mode - shows API calls
GH_DEBUG=api gh pr list

# Trace OAuth flow
GH_DEBUG=oauth gh auth login

# Full debugging
GH_DEBUG=api,oauth gh <command>

Check Configuration

# View current config
gh config list

# Check git remotes
git remote -v

# Verify default repository
gh repo view

# Check authentication
gh auth status

Inspect JSON Output

# Get full JSON response
gh pr view <number> --json

# Pretty print with jq
gh pr view <number> --json | jq .

# Inspect specific fields
gh pr view <number> --json state,title,number

Clear Cache

# If experiencing odd behavior, re-authenticate to refresh state
gh auth logout
gh auth login

# Or restart gh by closing all terminals and reopening
# Note: Cache will be automatically refreshed on next use

Network Issues

Connection Timeout

Error: dial tcp: i/o timeout

Solution:

# Check network connectivity
ping github.com

# Test GitHub API
curl -I https://api.github.com

# Use different network or VPN
# Check firewall/proxy settings

SSL Certificate Issues

Error: x509: certificate signed by unknown authority

Solution:

# Update ca-certificates
# macOS
brew install ca-certificates

# Set custom CA bundle if needed
export GH_CA_BUNDLE=/path/to/ca-bundle.crt

Getting Additional Help

Built-in Help

# Command-specific help
gh pr create --help
gh pr --help
gh --help

# View manual pages
man gh
man gh-pr

Check Version

# Current version
gh --version

# Check for updates
gh extension upgrade gh
brew upgrade gh  # macOS

Community Resources

• Official Manual: https://cli.github.com/manual
• GitHub CLI Repository: https://github.com/cli/cli
• Discussions: https://github.com/cli/cli/discussions
• Report Bugs: https://github.com/cli/cli/issues
• Stack Overflow: Tag github-cli

Common Error Codes

• 401: Authentication failed
• 403: Forbidden / insufficient permissions
• 404: Not found / no access
• 422: Validation failed / malformed request
• 500: GitHub server error

Workflows & Actions

Comprehensive guide for managing GitHub Actions workflows and runs using gh CLI.

Viewing Workflows

# List workflows
gh workflow list

# View workflow runs
gh run list

# View specific run
gh run view 789

# Watch run
gh run watch 789

# View run logs
gh run view 789 --log

Managing Workflows

# Trigger workflow
gh workflow run workflow.yml

# Cancel run
gh run cancel 789

# Rerun workflow
gh run rerun 789

# Download artifacts
gh run download 789

Workflow Runs

Advanced commands for managing workflow runs.

List and View Runs

# List recent workflow runs
gh run list

# List runs for specific workflow
gh run list --workflow=ci.yml

# List runs on specific branch
gh run list --branch=main

# List failed runs only
gh run list --status=failure

# Limit number of results
gh run list --limit=10

# View specific run details
gh run view 123456

# View run with logs
gh run view 123456 --log

# View run and open in browser
gh run view 123456 --web

# View specific job in a run
gh run view 123456 --job=123

# View run with exit status
gh run view 123456 --exit-status

Monitor and Control Runs

# Watch a run in real-time
gh run watch 123456

# Watch with interval (default 3s)
gh run watch 123456 --interval=5

# Cancel running workflow
gh run cancel 123456

# Rerun failed jobs only
gh run rerun 123456 --failed

# Rerun all jobs in a workflow run
gh run rerun 123456

# Rerun specific job
gh run rerun 123456 --job=123

Download Artifacts

# Download all artifacts from a run
gh run download 123456

# Download specific artifact by name
gh run download 123456 --name artifact-name

# Download to specific directory
gh run download 123456 --dir ./downloads

# Download artifacts from latest run
gh run download

# Download artifacts from specific workflow
gh run download --name=build-artifacts

Workflow Dispatch

Trigger workflows with custom inputs.

# Trigger workflow with inputs
gh workflow run deploy.yml -f environment=production -f version=v1.2.3

# Trigger workflow on specific branch
gh workflow run ci.yml --ref feature-branch

# Trigger workflow and get the run ID
RUN_ID=$(gh workflow run ci.yml --json url --jq '.url | split("/") | .[-1]')

GitHub Actions Cache

Manage GitHub Actions cache to optimize workflow performance.

# List caches in repository
gh cache list

# List caches for specific branch
gh cache list --ref refs/heads/main

# List caches with specific key
gh cache list --key npm-cache

# Sort caches by size
gh cache list --sort size

# Limit number of results
gh cache list --limit 10

CI/CD Integration Patterns

Trigger Workflow and Wait

# Trigger workflow and wait for completion
gh workflow run ci.yml --ref main && \
  sleep 5 && \
  gh run watch $(gh run list --workflow=ci.yml --limit 1 --json databaseId -q '.[0].databaseId')

# More robust version with retry
gh workflow run ci.yml --ref main
sleep 3
RUN_ID=$(gh run list --workflow=ci.yml --limit 1 --json databaseId -q '.[0].databaseId')
gh run watch $RUN_ID

Check CI Status Before Merge

# Check all checks pass before merging
gh pr checks 123 && gh pr merge 123 --squash

# Wait for checks to complete
gh pr checks 123 --watch && gh pr merge 123 --squash

# Check specific required checks
gh pr view 123 --json statusCheckRollup --jq '.statusCheckRollup[] | select(.conclusion != "SUCCESS")'

Auto-merge on Success

# Enable auto-merge when checks pass
gh pr merge 123 --auto --squash

# Enable auto-merge with specific merge method
gh pr merge 123 --auto --merge
gh pr merge 123 --auto --rebase

# Disable auto-merge
gh pr merge 123 --disable-auto

Monitor Multiple Workflows

# Watch all active workflow runs
gh run list --status=in_progress --json databaseId,name,headBranch | \
  jq -r '.[] | "\(.databaseId) - \(.name) on \(.headBranch)"'

# Check status of all workflows for current commit
COMMIT=$(git rev-parse HEAD)
gh run list --commit=$COMMIT --json status,conclusion,name

Workflow Run Analytics

# Get average duration for workflow
gh run list --workflow=ci.yml --limit=50 --json createdAt,updatedAt,conclusion | \
  jq '[.[] | select(.conclusion == "success") |
    ((.updatedAt | fromdateiso8601) - (.createdAt | fromdateiso8601))] |
    add / length / 60'

# Count failed runs in last 30 days
gh run list --created=">=$(date -v-30d +%Y-%m-%d)" --status=failure --json id | jq '. | length'

# List slowest workflow runs
gh run list --workflow=ci.yml --limit=20 --json databaseId,createdAt,updatedAt,conclusion | \
  jq 'sort_by((.updatedAt | fromdateiso8601) - (.createdAt | fromdateiso8601)) | reverse | .[:5]'

Conditional Workflow Execution

# Trigger workflow only if tests pass locally
npm test && gh workflow run deploy.yml -f environment=staging

# Chain workflows
gh workflow run build.yml && \
  sleep 10 && \
  gh run watch $(gh run list --workflow=build.yml --limit 1 -q '.[0].databaseId') && \
  gh workflow run deploy.yml

Retrieve Workflow Job Logs

# Download logs for a specific run
gh run view 123456 --log > workflow-logs.txt

# Download logs for failed jobs only
gh run view 123456 --log-failed > failed-jobs.txt

# View logs for specific job
gh api repos/:owner/:repo/actions/jobs/JOB_ID/logs > job.log

Advanced Workflow Management

Using JSON Output for Scripting

# Get workflow run details as JSON
gh run view 123456 --json status,conclusion,startedAt,url

# Parse specific fields
gh run view 123456 --json conclusion -q '.conclusion'

# List all failed runs with details
gh run list --status=failure --json databaseId,name,headBranch,conclusion,createdAt

# Get workflow run URL programmatically
gh run view 123456 --json url -q '.url'

Workflow Environment Secrets

# List repository secrets (requires admin access)
gh secret list

# Set a secret
gh secret set SECRET_NAME < secret.txt
gh secret set SECRET_NAME --body "secret-value"

# List organization secrets
gh secret list --org organization-name

Workflow Variables

# List repository variables
gh variable list

# Set a variable
gh variable set VAR_NAME --body "value"

Troubleshooting

Debug Failed Runs

# View failed run with logs
gh run view 123456 --log-failed

# List failed jobs in a run
gh run view 123456 --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion}'

# Rerun failed jobs with debug logging
gh run rerun 123456 --failed --debug

Check Workflow File Syntax

# View workflow file
gh workflow view ci.yml

# Download workflow file
gh api repos/:owner/:repo/contents/.github/workflows/ci.yml --jq '.content' | base64 -d

# List all workflow files
gh api repos/:owner/:repo/contents/.github/workflows --jq '.[] | .name'

Best Practices

01. Use specific workflow names when triggering or listing runs to avoid ambiguity 02. Enable auto-merge for PRs to merge automatically when CI passes 03. Monitor workflow cache regularly to prevent cache bloat 04. Use JSON output for scripting and automation 05. Watch runs interactively during development to catch failures quickly 06. Clean up old workflow runs to keep repository tidy 07. Use workflow dispatch inputs for flexible, reusable workflows 08. Set appropriate timeouts to prevent workflows from running indefinitely 09. Use artifacts judiciously - they count against storage limits 10. Leverage caching to speed up workflows and reduce costs