GitHub Operations Skill

Complete GitHub integration via the gh CLI. This skill provides 90+ operations covering all aspects of GitHub: repositories, issues, pull requests, Actions, security, discussions, projects, notifications, and more.

Prerequisites

• gh CLI installed: Install from https://cli.github.com/
• Authenticated: Run gh auth login to authenticate
• Verify: Run gh auth status to confirm authentication

Quick Reference

Repository Operations

Issue Operations

Pull Request Operations

Actions Workflows

Detailed Operations by Category

1. Repository Management (repos)

Get File Contents

Read files or directories from a repository.

bash
1# Read a specific file
2gh api repos/{owner}/{repo}/contents/{path} | jq -r '.content' | base64 -d
3
4# Simpler: use gh to browse
5gh browse --repo owner/repo -- path/to/file
6
7# Get raw file content
8gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 --decode

Search Repositories

bash
1# Search public repositories
2gh search repos "query" --limit 10
3
4# Search with filters
5gh search repos "language:python stars:>1000" --limit 20
6
7# Search in specific org
8gh search repos "org:microsoft language:typescript"

Search Code

bash
1# Search code across repositories
2gh search code "function authenticate" --limit 10
3
4# Search in specific repo
5gh search code "TODO" --repo owner/repo
6
7# Search with file extension filter
8gh search code "import pandas" --extension py

Create Repository

bash
1# Create public repo
2gh repo create my-repo --public --description "My new repo"
3
4# Create private repo with README
5gh repo create my-repo --private --add-readme
6
7# Create from template
8gh repo create my-repo --template owner/template-repo
9
10# Create in organization
11gh repo create org/my-repo --public

Fork Repository

bash
1# Fork to your account
2gh repo fork owner/repo
3
4# Fork and clone
5gh repo fork owner/repo --clone
6
7# Fork to organization
8gh repo fork owner/repo --org my-org

Manage Branches

bash
1# List branches
2gh api repos/{owner}/{repo}/branches --jq '.[].name'
3
4# Create branch (via git)
5git checkout -b new-branch && git push -u origin new-branch
6
7# Delete branch
8gh api -X DELETE repos/{owner}/{repo}/git/refs/heads/{branch}

Get Commits

bash
1# List recent commits
2gh api repos/{owner}/{repo}/commits --jq '.[] | {sha: .sha[:7], message: .commit.message, author: .commit.author.name}'
3
4# Get specific commit
5gh api repos/{owner}/{repo}/commits/{sha}
6
7# List commits on branch
8gh api "repos/{owner}/{repo}/commits?sha={branch}" --jq '.[] | .sha[:7] + " " + .commit.message'

Create/Update Files

bash
1# Create or update a file
2gh api repos/{owner}/{repo}/contents/{path} \
3  -X PUT \
4  -f message="Commit message" \
5  -f content="$(echo -n 'file content' | base64)" \
6  -f branch="main"
7
8# Update existing file (need sha)
9SHA=$(gh api repos/{owner}/{repo}/contents/{path} --jq '.sha')
10gh api repos/{owner}/{repo}/contents/{path} \
11  -X PUT \
12  -f message="Update file" \
13  -f content="$(echo -n 'new content' | base64)" \
14  -f sha="$SHA"

Delete Files

bash
1# Delete a file
2SHA=$(gh api repos/{owner}/{repo}/contents/{path} --jq '.sha')
3gh api repos/{owner}/{repo}/contents/{path} \
4  -X DELETE \
5  -f message="Delete file" \
6  -f sha="$SHA"

Releases

bash
1# List releases
2gh release list --repo owner/repo
3
4# Get latest release
5gh release view --repo owner/repo
6
7# Get specific release
8gh release view v1.0.0 --repo owner/repo
9
10# Create release
11gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes"
12
13# Upload assets
14gh release upload v1.0.0 ./dist/*.zip

Tags

bash
1# List tags
2gh api repos/{owner}/{repo}/tags --jq '.[].name'
3
4# Get tag details
5gh api repos/{owner}/{repo}/git/refs/tags/{tag}

Repository Tree

bash
1# Get full repository tree
2gh api repos/{owner}/{repo}/git/trees/main?recursive=1 --jq '.tree[] | select(.type=="blob") | .path'
3
4# Get tree for specific directory
5gh api repos/{owner}/{repo}/contents/{path} --jq '.[] | .name + (if .type == "dir" then "/" else "" end)'

2. Issues Management (issues)

Create Issue

bash
1# Basic issue creation
2gh issue create --title "Bug: Something is broken" --body "Description here"
3
4# With labels and assignees
5gh issue create --title "Feature request" --body "Details" --label "enhancement" --assignee "@me"
6
7# With milestone
8gh issue create --title "Task" --body "Description" --milestone "v1.0"
9
10# Interactive mode
11gh issue create

List Issues

bash
1# List open issues
2gh issue list
3
4# List with filters
5gh issue list --state closed --label "bug" --limit 50
6
7# List assigned to me
8gh issue list --assignee "@me"
9
10# List by author
11gh issue list --author username
12
13# Search issues
14gh issue list --search "is:open label:bug sort:updated-desc"

Read Issue

bash
1# View issue details
2gh issue view 123
3
4# View with comments
5gh issue view 123 --comments
6
7# JSON output for parsing
8gh issue view 123 --json title,body,state,labels,assignees

Update Issue

bash
1# Edit title/body
2gh issue edit 123 --title "New title" --body "New body"
3
4# Add labels
5gh issue edit 123 --add-label "priority:high,needs-review"
6
7# Remove labels
8gh issue edit 123 --remove-label "wontfix"
9
10# Assign users
11gh issue edit 123 --add-assignee username1,username2
12
13# Set milestone
14gh issue edit 123 --milestone "v2.0"

Close/Reopen Issues

bash
1# Close issue
2gh issue close 123
3
4# Close with comment
5gh issue close 123 --comment "Fixed in PR #456"
6
7# Close as not planned
8gh issue close 123 --reason "not planned"
9
10# Reopen issue
11gh issue reopen 123

Issue Comments

bash
1# Add comment
2gh issue comment 123 --body "This is my comment"
3
4# Add comment from file
5gh issue comment 123 --body-file ./comment.md
6
7# Edit comment (via API)
8gh api repos/{owner}/{repo}/issues/comments/{comment_id} \
9  -X PATCH \
10  -f body="Updated comment"

Search Issues

bash
1# Search across all repos
2gh search issues "memory leak" --limit 20
3
4# Search in specific repo
5gh search issues "bug" --repo owner/repo
6
7# Advanced search
8gh search issues "is:open is:issue label:bug author:username"

Labels

bash
1# List labels
2gh label list
3
4# Create label
5gh label create "priority:critical" --color FF0000 --description "Critical priority"
6
7# Edit label
8gh label edit "bug" --new-name "type:bug" --color 00FF00
9
10# Delete label
11gh label delete "old-label" --yes

Sub-Issues (Parent/Child)

bash
1# Add sub-issue relationship via API
2gh api graphql -f query='
3mutation {
4  addSubIssue(input: {issueId: "PARENT_ID", subIssueId: "CHILD_ID"}) {
5    issue { number }
6  }
7}'

3. Pull Requests (pull_requests)

Create Pull Request

bash
1# Basic PR creation
2gh pr create --title "Add new feature" --body "Description"
3
4# From specific branch to base
5gh pr create --base main --head feature-branch --title "Title"
6
7# Draft PR
8gh pr create --title "WIP: Feature" --draft
9
10# With reviewers
11gh pr create --title "Feature" --reviewer user1,user2
12
13# From fork
14gh pr create --repo upstream/repo --head myuser:feature-branch

List Pull Requests

bash
1# List open PRs
2gh pr list
3
4# List with filters
5gh pr list --state merged --base main --limit 50
6
7# List by author
8gh pr list --author "@me"
9
10# Search PRs
11gh pr list --search "is:open review:required"

Read Pull Request

bash
1# View PR details
2gh pr view 123
3
4# View with diff
5gh pr diff 123
6
7# View specific file diff
8gh pr diff 123 -- path/to/file
9
10# JSON output
11gh pr view 123 --json title,body,state,reviewDecision,mergeable

Update Pull Request

bash
1# Edit title/body
2gh pr edit 123 --title "New title" --body "New body"
3
4# Add labels
5gh pr edit 123 --add-label "needs-review"
6
7# Add reviewers
8gh pr edit 123 --add-reviewer user1,team/reviewers
9
10# Mark ready for review
11gh pr ready 123

Merge Pull Request

bash
1# Merge with merge commit
2gh pr merge 123 --merge
3
4# Squash merge
5gh pr merge 123 --squash
6
7# Rebase merge
8gh pr merge 123 --rebase
9
10# Auto-merge when checks pass
11gh pr merge 123 --auto --squash
12
13# Delete branch after merge
14gh pr merge 123 --delete-branch

PR Reviews

bash
1# Approve PR
2gh pr review 123 --approve
3
4# Request changes
5gh pr review 123 --request-changes --body "Please fix X"
6
7# Comment without approval
8gh pr review 123 --comment --body "Looks good overall"
9
10# View reviews
11gh pr view 123 --json reviews --jq '.reviews[] | {author: .author.login, state: .state}'

PR Comments

bash
1# Add comment to PR
2gh pr comment 123 --body "Comment text"
3
4# Add review comment on specific line (via API)
5gh api repos/{owner}/{repo}/pulls/{pr}/comments \
6  -f body="Review comment" \
7  -f commit_id="SHA" \
8  -f path="file.py" \
9  -F line=42

Update PR Branch

bash
1# Update branch with base
2gh pr update-branch 123
3
4# Via API
5gh api repos/{owner}/{repo}/pulls/{pr}/update-branch -X PUT

Search Pull Requests

bash
1# Search PRs
2gh search prs "fix bug" --limit 20
3
4# Search with filters
5gh search prs "is:open review:approved base:main"

Checkout PR

bash
1# Checkout PR locally
2gh pr checkout 123
3
4# Checkout to specific branch name
5gh pr checkout 123 --branch my-review-branch

4. GitHub Actions (actions)

List Workflows

bash
1# List all workflows
2gh workflow list
3
4# Show disabled workflows too
5gh workflow list --all

Run Workflow

bash
1# Trigger workflow
2gh workflow run workflow.yml
3
4# With inputs
5gh workflow run workflow.yml -f param1=value1 -f param2=value2
6
7# On specific branch
8gh workflow run workflow.yml --ref feature-branch

List Workflow Runs

bash
1# List recent runs
2gh run list
3
4# Filter by workflow
5gh run list --workflow=ci.yml
6
7# Filter by status
8gh run list --status failure --limit 10
9
10# Filter by branch
11gh run list --branch main

View Workflow Run

bash
1# View run details
2gh run view 123456789
3
4# View with job details
5gh run view 123456789 --verbose
6
7# JSON output
8gh run view 123456789 --json status,conclusion,jobs

Get Run Logs

bash
1# View logs interactively
2gh run view 123456789 --log
3
4# Download logs
5gh run view 123456789 --log > run.log
6
7# Failed jobs only
8gh run view 123456789 --log-failed

Watch Running Workflow

bash
1# Watch run until completion
2gh run watch 123456789
3
4# Exit with run's exit code
5gh run watch 123456789 --exit-status

Rerun Workflows

bash
1# Rerun entire workflow
2gh run rerun 123456789
3
4# Rerun failed jobs only
5gh run rerun 123456789 --failed
6
7# Rerun with debug logging
8gh run rerun 123456789 --debug

Cancel Workflow Run

bash
1# Cancel running workflow
2gh run cancel 123456789

Download Artifacts

bash
1# Download all artifacts
2gh run download 123456789
3
4# Download specific artifact
5gh run download 123456789 --name artifact-name
6
7# Download to specific directory
8gh run download 123456789 --dir ./artifacts

List Artifacts

bash
1# List run artifacts
2gh api repos/{owner}/{repo}/actions/runs/{run_id}/artifacts --jq '.artifacts[] | {name: .name, size: .size_in_bytes}'

Delete Workflow Run Logs

bash
1gh api -X DELETE repos/{owner}/{repo}/actions/runs/{run_id}/logs

Workflow Run Usage

bash
1gh api repos/{owner}/{repo}/actions/runs/{run_id}/timing

List Jobs in Run

bash
1gh api repos/{owner}/{repo}/actions/runs/{run_id}/jobs --jq '.jobs[] | {name: .name, status: .status, conclusion: .conclusion}'

Get Job Logs

bash
1gh api repos/{owner}/{repo}/actions/jobs/{job_id}/logs

5. Code Security (code_security)

Code Scanning Alerts

bash
1# List code scanning alerts
2gh api repos/{owner}/{repo}/code-scanning/alerts --jq '.[] | {number: .number, rule: .rule.id, severity: .rule.severity, state: .state}'
3
4# Get specific alert
5gh api repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
6
7# Filter by state
8gh api "repos/{owner}/{repo}/code-scanning/alerts?state=open" --jq '.[] | {number: .number, rule: .rule.id}'
9
10# Filter by severity
11gh api "repos/{owner}/{repo}/code-scanning/alerts?severity=critical,high"

Dismiss Code Scanning Alert

bash
1gh api repos/{owner}/{repo}/code-scanning/alerts/{alert_number} \
2  -X PATCH \
3  -f state="dismissed" \
4  -f dismissed_reason="false positive"

6. Dependabot (dependabot)

List Dependabot Alerts

bash
1# List all alerts
2gh api repos/{owner}/{repo}/dependabot/alerts --jq '.[] | {number: .number, package: .dependency.package.name, severity: .security_advisory.severity}'
3
4# Filter by severity
5gh api "repos/{owner}/{repo}/dependabot/alerts?severity=critical,high"
6
7# Filter by state
8gh api "repos/{owner}/{repo}/dependabot/alerts?state=open"

Get Specific Alert

bash
1gh api repos/{owner}/{repo}/dependabot/alerts/{alert_number}

Dismiss Dependabot Alert

bash
1gh api repos/{owner}/{repo}/dependabot/alerts/{alert_number} \
2  -X PATCH \
3  -f state="dismissed" \
4  -f dismissed_reason="tolerable_risk"

7. Secret Scanning (secret_protection)

List Secret Scanning Alerts

bash
1# List alerts
2gh api repos/{owner}/{repo}/secret-scanning/alerts --jq '.[] | {number: .number, secret_type: .secret_type, state: .state}'
3
4# Filter by state
5gh api "repos/{owner}/{repo}/secret-scanning/alerts?state=open"

Get Secret Scanning Alert

bash
1gh api repos/{owner}/{repo}/secret-scanning/alerts/{alert_number}

Update Secret Scanning Alert

bash
1gh api repos/{owner}/{repo}/secret-scanning/alerts/{alert_number} \
2  -X PATCH \
3  -f state="resolved" \
4  -f resolution="revoked"

8. Security Advisories (security_advisories)

List Global Advisories

bash
1# List recent advisories
2gh api /advisories --jq '.[] | {ghsa_id: .ghsa_id, severity: .severity, summary: .summary}'
3
4# Filter by ecosystem
5gh api "/advisories?ecosystem=npm" --jq '.[] | .ghsa_id'
6
7# Filter by severity
8gh api "/advisories?severity=critical"

Get Specific Advisory

bash
1gh api /advisories/{ghsa_id}

Repository Security Advisories

bash
1# List repo advisories
2gh api repos/{owner}/{repo}/security-advisories
3
4# Create draft advisory
5gh api repos/{owner}/{repo}/security-advisories \
6  -X POST \
7  -f summary="Security issue" \
8  -f description="Details" \
9  -f severity="high"

9. Discussions (discussions)

List Discussions

bash
1# Via GraphQL (discussions require GraphQL)
2gh api graphql -f query='
3query($owner: String!, $repo: String!) {
4  repository(owner: $owner, name: $repo) {
5    discussions(first: 10) {
6      nodes {
7        number
8        title
9        author { login }
10        category { name }
11      }
12    }
13  }
14}' -f owner="{owner}" -f repo="{repo}"

Get Discussion

bash
1gh api graphql -f query='
2query($owner: String!, $repo: String!, $number: Int!) {
3  repository(owner: $owner, name: $repo) {
4    discussion(number: $number) {
5      title
6      body
7      author { login }
8      comments(first: 10) {
9        nodes { body author { login } }
10      }
11    }
12  }
13}' -f owner="{owner}" -f repo="{repo}" -F number=123

Create Discussion

bash
1# First get category ID
2CATEGORY_ID=$(gh api graphql -f query='
3query($owner: String!, $repo: String!) {
4  repository(owner: $owner, name: $repo) {
5    discussionCategories(first: 10) {
6      nodes { id name }
7    }
8  }
9}' -f owner="{owner}" -f repo="{repo}" --jq '.data.repository.discussionCategories.nodes[0].id')
10
11# Then create discussion
12gh api graphql -f query='
13mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
14  createDiscussion(input: {repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body}) {
15    discussion { number url }
16  }
17}'

Discussion Categories

bash
1gh api graphql -f query='
2query($owner: String!, $repo: String!) {
3  repository(owner: $owner, name: $repo) {
4    discussionCategories(first: 20) {
5      nodes { id name description }
6    }
7  }
8}' -f owner="{owner}" -f repo="{repo}"

10. Gists (gists)

Create Gist

bash
1# Create public gist
2gh gist create file.py --public --desc "My Python script"
3
4# Create secret gist
5gh gist create file1.py file2.py --desc "Multiple files"
6
7# Create from stdin
8echo "content" | gh gist create --filename "test.txt"

List Gists

bash
1# List your gists
2gh gist list
3
4# List with limit
5gh gist list --limit 50
6
7# Public only
8gh gist list --public

View Gist

bash
1# View gist
2gh gist view {gist_id}
3
4# View specific file
5gh gist view {gist_id} --filename file.py
6
7# Raw content
8gh gist view {gist_id} --raw

Edit Gist

bash
1# Edit gist interactively
2gh gist edit {gist_id}
3
4# Add file to gist
5gh gist edit {gist_id} --add newfile.py
6
7# Remove file
8gh gist edit {gist_id} --remove oldfile.py

Delete Gist

bash
1gh gist delete {gist_id}

Clone Gist

bash
1gh gist clone {gist_id}

11. Projects (projects)

List Projects

bash
1# User projects
2gh project list
3
4# Organization projects
5gh project list --owner org-name
6
7# Closed projects too
8gh project list --closed

View Project

bash
1# View project details
2gh project view {number}
3
4# JSON output
5gh project view {number} --format json

Create Project

bash
1# Create project
2gh project create --title "My Project"
3
4# In organization
5gh project create --title "Team Project" --owner org-name

Project Items

bash
1# List items in project
2gh project item-list {number}
3
4# Add issue to project
5gh project item-add {number} --url https://github.com/owner/repo/issues/123
6
7# Add PR to project
8gh project item-add {number} --url https://github.com/owner/repo/pull/456

Edit Project Item

bash
1# Archive item
2gh project item-archive {project_number} --id {item_id}
3
4# Delete item
5gh project item-delete {project_number} --id {item_id}
6
7# Edit field value
8gh project item-edit --project-id {project_id} --id {item_id} --field-id {field_id} --text "value"

Project Fields

bash
1# List fields
2gh project field-list {number}
3
4# Create field
5gh project field-create {number} --name "Priority" --data-type SINGLE_SELECT

12. Notifications (notifications)

List Notifications

bash
1# List unread notifications
2gh api notifications --jq '.[] | {id: .id, reason: .reason, title: .subject.title, repo: .repository.full_name}'
3
4# All notifications
5gh api "notifications?all=true"
6
7# Participating only
8gh api "notifications?participating=true"

Mark as Read

bash
1# Mark specific notification as read
2gh api -X PATCH notifications/threads/{thread_id}
3
4# Mark all as read
5gh api -X PUT notifications
6
7# Mark repo notifications as read
8gh api -X PUT repos/{owner}/{repo}/notifications

Notification Details

bash
1gh api notifications/threads/{thread_id}

Manage Subscription

bash
1# Subscribe to thread
2gh api -X PUT notifications/threads/{thread_id}/subscription \
3  -f ignored=false
4
5# Unsubscribe
6gh api -X PUT notifications/threads/{thread_id}/subscription \
7  -f ignored=true
8
9# Delete subscription
10gh api -X DELETE notifications/threads/{thread_id}/subscription

13. Users (users)

Get Current User

bash
1gh api user

Search Users

bash
1# Search users
2gh search users "username" --limit 10
3
4# Filter by type
5gh search users "type:user location:USA"
6
7# Search organizations
8gh search users "type:org language:python"

Get User Profile

bash
1gh api users/{username}

14. Organizations (organizations)

Search Organizations

bash
1gh search repos "org:{org-name}" --limit 10

Get Organization Details

bash
1gh api orgs/{org}

List Org Members

bash
1gh api orgs/{org}/members --jq '.[].login'

List Org Repos

bash
1gh repo list {org} --limit 100

Get Teams

bash
1gh api orgs/{org}/teams --jq '.[].name'

Get Team Members

bash
1gh api orgs/{org}/teams/{team_slug}/members --jq '.[].login'

15. Stargazers (stargazers)

Star Repository

bash
1gh api -X PUT user/starred/{owner}/{repo}

Unstar Repository

bash
1gh api -X DELETE user/starred/{owner}/{repo}

List Starred Repos

bash
1# Your starred repos
2gh api user/starred --jq '.[].full_name'
3
4# User's starred repos
5gh api users/{username}/starred --jq '.[].full_name'

Check if Starred

bash
1# Returns 204 if starred, 404 if not
2gh api user/starred/{owner}/{repo}

16. Context Information (context)

Get Authenticated User

bash
1gh api user --jq '{login: .login, name: .name, email: .email, company: .company}'

Authentication Status

bash
1gh auth status

Check Scopes

bash
1gh auth status --show-token 2>&1 | grep -i scope

Error Handling

Common Errors and Solutions

Check Rate Limits

bash
1gh api rate_limit --jq '.resources.core | {limit: .limit, remaining: .remaining, reset: .reset}'

Script Integration

This skill includes helper scripts in the scripts/ directory:

• github_helper.py - Python utilities for complex operations
• batch_operations.sh - Bash scripts for bulk actions

See reference.md for complete documentation.

Notes

• Always verify authentication before operations: gh auth status
• Use --json flag for programmatic output
• Use --jq for filtering JSON responses
• GraphQL API is required for some features (discussions, projects v2)
• Rate limits apply: 5000 requests/hour authenticated, 60/hour unauthenticated