GitHub Access

Overview

This skill enables programmatic access to GitHub repositories through either the gh CLI tool or the REST API with curl. Use this skill to interact with GitHub issues, pull requests, workflows, discussions, and GitHub Actions. The skill provides comprehensive commands and patterns for common GitHub operations.

Prerequisites and Tool Selection

Before performing any GitHub operations, follow this workflow:

1. Check for GH_TOKEN

CRITICAL: Always verify that the GH_TOKEN environment variable is set before attempting any GitHub operations:

echo $GH_TOKEN

If GH_TOKEN is not set:

• Abort the operation immediately
• Inform the user that a GitHub token is required
• Instruct them to set GH_TOKEN with a valid GitHub personal access token

Example message:

GitHub operations require authentication. Please set the GH_TOKEN environment variable with a valid GitHub personal access token:

export GH_TOKEN="your_token_here"

You can create a token at: https://github.com/settings/tokens

2. Check for gh CLI Availability

If GH_TOKEN is set, check if the gh CLI tool is available:

which gh

3. Load the Appropriate Reference

Based on availability, load the corresponding reference document:

• If gh is available: Read and use references/gh-commands.md for command examples
• If gh is NOT available: Read and use references/curl-api.md for REST API calls with curl

The references/mcp-tools.md file provides a comprehensive list of all available GitHub MCP tools and their parameters for reference.

Key Operations

These are the most commonly used GitHub operations. Detailed commands for both gh and curl are provided in the reference documents.

1. Read Issue Content

Use case: Get the full details of a GitHub issue including title, body, state, labels, and metadata.

When to use: When the user provides an issue number or URL, or when following up on search results.

With gh:

gh issue view ISSUE_NUMBER --repo OWNER/REPO
gh issue view ISSUE_NUMBER --json title,body,state,labels --repo OWNER/REPO

With curl:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER

2. Read Pull Request Comments

Use case: Retrieve comments and reviews on a pull request. GitHub has several types of PR comments:

• Regular comments: General discussion comments on the PR (use /issues/ endpoint)
• Review summaries: Top-level review with overall feedback (use /reviews endpoint)
• Inline review comments: Code-specific comments on file changes (use /pulls/.../comments endpoint)

When to use: When reviewing feedback on a PR, understanding discussion context, or analyzing review comments.

With gh:

# Get all comments and reviews
gh pr view PR_NUMBER --comments --repo OWNER/REPO

# Get as structured JSON
gh pr view PR_NUMBER --json comments,reviews --repo OWNER/REPO

With curl:

# Get all PR reviews (summary level with overall feedback)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/pulls/PR_NUMBER/reviews

# Get all inline review comments (code-specific comments on file changes)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/pulls/PR_NUMBER/comments

# Get regular PR comments (general discussion, not inline code comments)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/issues/PR_NUMBER/comments

# Get comments from a specific review (rarely needed - usually use /pulls/.../comments instead)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/pulls/PR_NUMBER/reviews/REVIEW_ID/comments

3. Check Workflow Status and Fetch Failure Logs

Use case: Diagnose CI/CD failures by checking workflow run status and retrieving logs from failed jobs.

When to use: When a PR has failing checks, when investigating build failures, or when debugging CI/CD issues.

With gh:

# 1. Check PR status
gh pr checks PR_NUMBER --repo OWNER/REPO

# 2. Get the most recent workflow run for the PR
RUN_ID=$(gh pr view PR_NUMBER --json headRefName --jq -r '.headRefName' | \
  xargs -I {} gh run list --branch {} --limit 1 --json databaseId --jq '.[0].databaseId' --repo OWNER/REPO)

# 3. View failed job logs
gh run view $RUN_ID --log-failed --repo OWNER/REPO

With curl:

# 1. Get PR details to find HEAD SHA
PR_DATA=$(curl -s -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/pulls/PR_NUMBER)

HEAD_SHA=$(echo "$PR_DATA" | jq -r '.head.sha')

# 2. Get check runs for that SHA
curl -s -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/commits/$HEAD_SHA/check-runs

# 3. Get failed workflow runs
RUNS=$(curl -s -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/OWNER/REPO/actions/runs?head_sha=$HEAD_SHA")

FAILED_RUN_ID=$(echo "$RUNS" | jq -r '.workflow_runs[] | select(.conclusion == "failure") | .id' | head -1)

# 4. Get failed jobs
curl -s -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/OWNER/REPO/actions/runs/$FAILED_RUN_ID/jobs?filter=failed"

# 5. Get logs for specific job
JOB_ID=$(curl -s -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/OWNER/REPO/actions/runs/$FAILED_RUN_ID/jobs?filter=failed" | jq -r '.jobs[0].id')

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/actions/jobs/$JOB_ID/logs

4. Search Issues

Use case: Find issues when the user doesn't provide a specific issue number or URL.

When to use: When the user mentions an issue by description, keyword, or topic rather than by number.

With gh:

# Search in specific repository
gh issue list --search "QUERY" --repo OWNER/REPO

# Search with filters
gh issue list --state open --label bug --repo OWNER/REPO

# Search across organization
gh search issues "QUERY" --owner OWNER

With curl:

# Search issues in repository
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/search/issues?q=QUERY+repo:OWNER/REPO+type:issue"

# Search with filters (e.g., open bugs)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/search/issues?q=is:open+label:bug+repo:OWNER/REPO+type:issue"

5. Search Pull Requests

Use case: Find pull requests when the user doesn't provide a specific PR number or URL.

When to use: When the user references a PR by description, author, branch name, or topic rather than by number.

With gh:

# Search in specific repository
gh pr list --search "QUERY" --repo OWNER/REPO

# Search with filters
gh pr list --state open --author USERNAME --repo OWNER/REPO

# Search across organization
gh search prs "QUERY" --owner OWNER

With curl:

# Search PRs in repository
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/search/issues?q=QUERY+repo:OWNER/REPO+type:pr"

# Search with filters (e.g., open PRs by author)
curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token $GH_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/search/issues?q=is:open+author:USERNAME+repo:OWNER/REPO+type:pr"

Extracting Repository Information

When the user provides a GitHub URL, extract the owner and repository name:

Example URL formats:

• https://github.com/owner/repo/issues/123
• https://github.com/owner/repo/pull/456
• https://github.com/owner/repo

Extraction with sed:

URL="https://github.com/owner/repo/issues/123"
OWNER_REPO=$(echo "$URL" | sed -E 's|https://github.com/([^/]+/[^/]+)/.*|\1|')
OWNER=$(echo "$OWNER_REPO" | cut -d'/' -f1)
REPO=$(echo "$OWNER_REPO" | cut -d'/' -f2)

Resources

This skill includes three reference documents with comprehensive command examples:

references/mcp-tools.md

Complete list of all available GitHub MCP tools and their parameters. Use this as a reference for understanding available functionality and parameter requirements.

references/gh-commands.md

Comprehensive gh CLI commands for all GitHub operations. Load this document when gh is available. Includes:

• Actions and workflow operations
• Issue management
• Pull request operations
• Discussions (via GraphQL)
• Common patterns and tips

Official documentation: https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28&tool=cli

references/curl-api.md

REST API calls using curl for environments without gh CLI. Load this document when gh is not available. Includes:

• Complete REST API endpoints
• Request headers and authentication
• Response parsing with jq
• GraphQL queries for discussions
• Pagination and rate limiting

Official documentation: https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28&tool=curl

Additional Operations

Beyond the key operations listed above, the reference documents provide detailed commands for:

• Workflows: Trigger, list, rerun, cancel, download artifacts
• Issues: Create, update, comment, label, assign, close
• Pull Requests: Create, update, merge, review, request reviewers, get diff
• Discussions: List, view, comment (via GraphQL)
• Labels: Get, create, update, delete
• Repository operations: Various repository-level operations

Consult the appropriate reference document (gh-commands.md or curl-api.md) for complete examples.