GitHub CLI Integration

Purpose

The GitHub CLI skill provides comprehensive repository management capabilities through the gh command-line tool. It enables developers and ClawdBot instances to automate GitHub workflows, manage issues and pull requests, review code, handle releases, monitor repository activity, and interact with GitHub Actions—all without leaving the terminal or Claude Code interface.

This skill bridges the gap between local development workflows and GitHub’s web interface, allowing for programmatic control and automation of common repository operations.

Triggers

Use this skill when you need to:

1. Create and manage issues – Create new issues, add labels, assign owners, set milestones, close/reopen issues
2. Create and manage pull requests – Open PRs, add reviewers, manage draft status, add descriptions and labels
3. Review code – View commits, diff changes, approve/request changes, add comments to specific lines
4. Manage releases – Create releases, tag versions, manage release notes, publish pre-releases
5. Track repository activity – Monitor recent commits, view workflow runs, check repository stats, list open issues/PRs
6. Work with GitHub Actions – Trigger workflows, check workflow status, view logs, manage CI/CD pipelines
7. Repository configuration – Update settings, manage branch protection, handle collaborators

Required Setup

Prerequisites

• gh CLI installed (https://cli.github.com)
• GitHub authentication configured via gh auth login
• Repository access and appropriate permissions

Installation

# macOS
brew install gh

# Linux
apt-get install gh  # Debian/Ubuntu
dnf install gh      # Fedora/RHEL
yay -S github-cli   # Arch

# Or download from https://github.com/cli/cli/releases

Authentication

gh auth login
# Follow the prompts to authenticate with GitHub
# Default authentication is stored in ~/.config/gh/hosts.yml

Capabilities

Issue Management

• Create new issues with title, body, labels, and assignees
• List issues with filtering by state, label, assignee, or milestone
• Update issue properties (title, body, labels, state)
• Add/remove labels from existing issues
• Assign/unassign issues
• Lock/unlock issues for discussion control

Pull Request Management

• Create pull requests with descriptions and reviewers
• List pull requests with filtering options
• View PR details, files changed, commits
• Request reviewers and assign PRs
• Mark PRs as draft/ready for review
• Merge PRs with custom commit messages
• Close PRs without merging

Code Review

• View commit details and commit messages
• Examine diffs between branches
• Add comments to commits
• Review file changes with context
• Check pull request review status
• Approve or request changes on PRs

Release Management

• Create releases with version tags
• Add release notes and descriptions
• Upload assets to releases
• Manage pre-releases and draft releases
• Delete releases
• View release history

Repository Activity Tracking

• View recent commits
• Check repository statistics (stars, forks, issues)
• List contributors and contribution counts
• Monitor branch activity
• Track open/closed issues and PRs by time period
• View workflow run history

GitHub Actions Integration

• List and view workflow definitions
• Trigger workflow runs manually
• Check workflow run status and results
• View workflow run logs
• Cancel running workflows
• Re-run failed jobs
• Manage workflow artifacts

Repository Configuration

• View repository settings
• Update repository metadata
• Manage branch protection rules
• List and manage repository secrets
• Handle SSH and deploy keys

Usage

Basic Command Structure

# All gh commands follow this pattern
gh <command> <subcommand> [options] [arguments]

# Examples:
gh issue create --title "Bug: Login fails" --body "Description..."
gh pr create --title "Feature: Add dark mode" --reviewer @username
gh release create v1.0.0 --notes "Release notes here"

Common Patterns

Creating Issues

gh issue create \
  --title "Issue title" \
  --body "Issue description" \
  --label "bug,help wanted" \
  --assignee "@me" \
  --milestone "v1.0"

Creating Pull Requests

gh pr create \
  --title "PR title" \
  --body "PR description" \
  --base main \
  --head feature-branch \
  --reviewer @user1,@user2 \
  --label "enhancement"

Reviewing Code

# View PR details
gh pr view 42

# View diff
gh pr diff 42

# Check review status
gh pr view 42 --json reviews

# Approve PR
gh pr review 42 --approve

# Request changes
gh pr review 42 --request-changes --body "Please fix..."

Managing Releases

# Create release
gh release create v1.0.0 \
  --title "Version 1.0.0" \
  --notes "Release notes here" \
  --draft

# View releases
gh release list

# Delete release
gh release delete v1.0.0

Tracking Activity

# View recent commits
gh api repos/{owner}/{repo}/commits

# Get repo stats
gh repo view --json stargazerCount,forkCount,issues

# List open PRs
gh pr list --state open

# List open issues
gh issue list --state open --label "bug"

GitHub Actions

# List workflows
gh workflow list

# Trigger workflow
gh workflow run workflow-name.yml

# View recent runs
gh run list

# Check run status
gh run view <run-id>

# View run logs
gh run view <run-id> --log

# Cancel running workflow
gh run cancel <run-id>

Examples

Example 1: Automated Issue Creation from Error

# Create an issue when a deployment fails
gh issue create \
  --title "Deployment failed in production" \
  --body "Deployment at $(date) failed with error: $ERROR_MESSAGE" \
  --label "critical,deployment" \
  --assignee "@devops-team"

Example 2: Code Review Workflow

# Check PR, add comment, approve
gh pr view 123
gh pr review 123 \
  --approve \
  --body "Looks good! Changes are solid."

Example 3: Release Management

# Create versioned release
VERSION="1.2.3"
gh release create "v$VERSION" \
  --title "Release $VERSION" \
  --notes "$(cat CHANGELOG.md)" \
  --target main

Example 4: GitHub Actions Monitoring

# Check latest workflow run
LATEST_RUN=$(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')
gh run view $LATEST_RUN --log

Example 5: Repository Statistics

# Get key repo metrics
gh api repos/{owner}/{repo} \
  --jq '.stargazers_count, .forks_count, .open_issues_count'

Example 6: Bulk Issue Management

# Close all issues with a label
gh issue list --label "duplicate" --json number --jq '.[].number' | \
  while read issue; do
    gh issue close $issue --reason duplicate
  done

Best Practices

1. Automation Safety

   • Always use --draft when auto-creating PRs to prevent accidental merges
   • Require approval for critical operations like releases
   • Use appropriate labels to categorize automated actions

2. Authentication

   • Store credentials securely in ~/.config/gh/hosts.yml
   • Use gh auth status to verify authentication
   • Rotate tokens regularly for security

3. Error Handling

   • Check command exit codes in scripts
   • Use --json output for reliable parsing
   • Validate repository and branch names before operations

4. Performance

   • Use filtering options (--state, --label) to reduce API calls
   • Batch operations when possible
   • Cache results when repeated queries aren’t needed

5. Logging and Audits

   • Log all automated operations with timestamps
   • Include operation context in issue/PR descriptions
   • Track who triggered operations and when

Integration with ClawdBot

This skill integrates seamlessly with ClawdBot’s automation capabilities:

• Use /github command to trigger GitHub operations
• Chain with other skills for complex workflows
• Maintain audit trails of all automated operations
• Support both synchronous and asynchronous operations

Resources

• Official Documentation: https://cli.github.com/manual
• GitHub API Reference: https://docs.github.com/en/rest
• gh CLI Repository: https://github.com/cli/cli
• GitHub CLI Extensions: https://github.com/topics/gh-extension

Support and Troubleshooting

Common Issues

Authentication Error

gh auth logout
gh auth login

Command Not Found

• Ensure gh is installed: which gh
• Check PATH includes gh installation

API Rate Limiting

• Check rate limit status: gh api rate_limit
• Wait for limit reset or upgrade GitHub account

Permission Denied

• Verify your GitHub account has repository access
• Check token scopes: gh auth status

For additional help, visit the GitHub CLI documentation or file an issue on the gh repository.