Github Operations

Working with GitHub URLs

When given a GitHub HTTPS URL, always convert it to the gh CLI format using --repo owner/repo rather than using the URL directly.

URL Pattern Reference

URL Conversion Examples

Pull Request URL:

# Given: https://github.com/topdatascience/metsa_backend/pull/1
# Extract: owner=topdatascience, repo=metsa_backend, number=1

gh pr view 1 --repo topdatascience/metsa_backend
gh pr checkout 1 --repo topdatascience/metsa_backend
gh pr merge 1 --repo topdatascience/metsa_backend --squash

Issue URL:

# Given: https://github.com/org/project/issues/42
# Extract: owner=org, repo=project, number=42

gh issue view 42 --repo org/project
gh issue comment 42 --repo org/project --body "Looking into this"

Actions Run URL:

# Given: https://github.com/org/repo/actions/runs/123456789
# Extract: owner=org, repo=repo, run-id=123456789

gh run view 123456789 --repo org/repo
gh run view 123456789 --repo org/repo --log-failed

Why Prefer --repo Over URLs

1. Consistency: All gh commands use the same --repo owner/repo format
2. Flexibility: Easy to modify owner/repo without URL encoding issues
3. Composability: Can chain commands using the same repo reference
4. Clarity: Command intent is immediately visible

Claude Attribution

When posting comments or reviews on behalf of the user, always include the Claude signature at the end of the message body to indicate it was AI-generated.

Signature Format

🤖 Generated with [Claude Code](https://claude.ai/code)

Usage Examples

PR Review with signature:

gh pr review 42 --approve --body "$(cat <<'EOF'
LGTM! The implementation looks solid.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

Issue comment with signature:

gh issue comment 15 --body "$(cat <<'EOF'
I've identified the root cause - the timeout occurs because...

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

PR comment with signature:

gh pr comment 7 --body "$(cat <<'EOF'
This approach could cause a race condition. Consider using a mutex here.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

When to Include

Instructions

Step 1: Determine Operation Type

Identify which GitHub operation is needed:

• PR operations: creation, review, merge, checkout
• Issue operations: creation, management, comments
• Actions: workflow monitoring, job management
• Search: finding issues/PRs across repos

Step 2: Execute Operation

Pull Request Operations

Create PR (from current branch, include Claude signature in body):

gh pr create --title "Feature: Add login" --body "$(cat <<'EOF'
Implements user authentication.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

Create PR with template:

gh pr create --fill  # Uses PR template

List open PRs:

gh pr list --state open
gh pr list --author @me  # Your PRs only

View PR details:

gh pr view [number]
gh pr view [number] --web  # Open in browser

Checkout PR locally:

gh pr checkout [number]

Merge PR:

gh pr merge [number] --squash  # Squash merge
gh pr merge [number] --merge   # Merge commit
gh pr merge [number] --rebase  # Rebase merge

Review PR (include Claude signature):

gh pr review [number] --approve --body "$(cat <<'EOF'
LGTM!

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"
gh pr review [number] --request-changes --body "$(cat <<'EOF'
Please fix the null check on line 42.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

See {baseDir}/references/gh-pr-workflows.md for advanced patterns.

Issue Operations

Create issue (include Claude signature in body):

gh issue create --title "Bug: Login fails" --body "$(cat <<'EOF'
Steps to reproduce...

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"
gh issue create --label bug --assignee @me --title "Bug title" --body "$(cat <<'EOF'
Description here.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

List issues:

gh issue list --state open
gh issue list --label bug --state open
gh issue list --assignee @me

View issue:

gh issue view [number]

Comment on issue (include Claude signature):

gh issue comment [number] --body "$(cat <<'EOF'
Working on this now.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

Close issue:

gh issue close [number]
gh issue close [number] --comment "$(cat <<'EOF'
Fixed in PR #123.

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

See {baseDir}/references/gh-issue-workflows.md for advanced patterns.

GitHub Actions Operations

List recent runs:

gh run list
gh run list --workflow=ci.yml
gh run list --status failure

View run details:

gh run view [run-id]
gh run view [run-id] --log  # Full logs
gh run view [run-id] --log-failed  # Failed job logs only

Watch running workflow:

gh run watch [run-id]

Re-run failed jobs:

gh run rerun [run-id] --failed

See {baseDir}/references/gh-actions-workflows.md for advanced patterns.

Search Operations

Search issues:

gh search issues "bug login" --repo owner/repo
gh search issues "is:open label:bug"

Search PRs:

gh search prs "feature" --state open
gh search prs "author:@me is:merged"

Step 3: Verify Result

After each operation:

1. Check command output for success/error messages
2. For PRs/issues, note the URL returned
3. For Actions, verify workflow status

Output

• PR/Issue URLs: Links to created/modified items
• Status messages: Success/failure confirmations
• Workflow status: Run state and results

Error Handling

1. Error: gh: command not found Cause: gh CLI not installed Solution: Install via brew install gh or see https://cli.github.com

2. Error: You are not logged into any GitHub hosts Cause: Not authenticated Solution: Run gh auth login and follow prompts

3. Error: Could not resolve to a Repository Cause: Not in a git repo or repo not on GitHub Solution: Ensure you're in a git repo with GitHub remote

4. Error: HTTP 403: Resource not accessible Cause: Insufficient permissions Solution: Check repo access or request permissions

5. Error: pull request create failed: GraphQL: No commits between main and feature Cause: No changes to merge Solution: Ensure branch has commits ahead of base

Examples

Example 1: Create and Merge PR

User Request: "Create a PR for my feature branch"

Commands:

# Create PR with auto-fill from commits
gh pr create --fill

# After review, merge with squash
gh pr merge --squash --delete-branch

Example 2: Triage Issues

User Request: "Show me open bugs assigned to me"

Command:

gh issue list --label bug --assignee @me --state open

Output:

Showing 2 of 2 issues

#42  Login timeout on slow networks    bug, priority:high   about 2 hours ago
#38  Session expires unexpectedly      bug                  about 1 day ago

Example 3: Debug Failed Workflow

User Request: "The CI failed, show me what went wrong"

Commands:

# List recent failed runs
gh run list --status failure --limit 5

# View logs for specific run
gh run view [run-id] --log-failed

Resources

• PR workflows: {baseDir}/references/gh-pr-workflows.md
• Issue workflows: {baseDir}/references/gh-issue-workflows.md
• Actions workflows: {baseDir}/references/gh-actions-workflows.md
• Official docs: https://cli.github.com/manual/