Advanced

API Limitations

GitHub API constraints and workarounds

API Limitations

Understanding GitHub API limitations helps you work effectively with gh-please.

Review Comment Replies

ID Format Support (v0.11.0+)

All comment operations support both ID formats with automatic detection:

Database ID (numeric):

Example: 1234567890
Found in GitHub UI URLs (discussion_r1234567890)
Automatically converted to Node ID via REST API

Node ID (string):

Example: PRRC_kwDOP34zbs6ShH0J (PR review comment)
Example: IC_kwDOABC123 (issue comment)
Used directly in GraphQL operations
No conversion needed

The CLI automatically detects ID format and handles conversion transparently. Both formats work identically from user perspective.

Top-Level Comments Only

The GitHub API endpoint used for replies:

POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies

Important: This endpoint only accepts top-level review comments as comment_id.

What Works

✅ Replying to review comments on specific lines (both ID formats)

gh please pr review reply 1234567890 -b "Fixed!"                 # Database ID
gh please pr review reply PRRC_kwDOP34zbs6ShH0J -b "Fixed!"     # Node ID

✅ Replying to review comments on files

gh please pr review reply 9876543210 -b "Good catch!"

What Doesn't Work

❌ Replying to replies (nested replies)

# This will fail if the comment is already a reply
gh please pr review reply <nested-reply-id> -b "..."
# Error: Not Found

Workaround: Reply on GitHub web UI for nested comments.

Rate Limits

GitHub API has rate limits for all operations.

Limits for Authenticated Requests

Via gh CLI (authenticated):

5,000 requests per hour for user-server requests
1,000 requests per hour for GraphQL API

Check Current Rate Limit

# REST API
gh api rate_limit

# GraphQL API
gh api graphql -f query='{ rateLimit { remaining resetAt } }'

Rate Limit Response

{
  "resources": {
    "core": {
      "limit": 5000,
      "remaining": 4999,
      "reset": 1680000000
    },
    "graphql": {
      "limit": 1000,
      "remaining": 999,
      "reset": 1680000000
    }
  }
}

Handling Rate Limits

If you hit rate limits:

Wait for reset - Check resetAt timestamp
Reduce requests - Batch operations when possible
Use conditional requests - Cache responses with ETags

GraphQL API

Sub-Issues Feature Flag

Sub-issue mutations require special header:

gh api graphql \
  -H "GraphQL-Features: sub_issues" \
  -f query='...'

Why: Sub-issues are a beta feature requiring opt-in.

Node ID Format

GraphQL uses Node IDs (not numeric IDs):

# Numeric ID / Database ID (REST)
123                      # Issue/PR number
1234567890              # Comment Database ID

# Node ID (GraphQL)
I_kwDOABcdEF4GHijKL     # Issue
PR_kwDOXYZ123           # Pull Request
PRRC_kwDOP34zbs6ShH0J   # PR Review Comment
IC_kwDOABC123           # Issue Comment

Automatic Conversion (v0.11.0+):

The CLI now handles ID conversion automatically:

# Database ID → Node ID (automatic)
gh please pr review reply 1234567890 -b "Fixed!"

# Node ID → Direct use (no conversion)
gh please pr review reply PRRC_kwDOP34zbs6ShH0J -b "Fixed!"

Manual Conversion (for custom scripts):

// Get Node ID from numeric ID (if needed)
const nodeId = await getIssueNodeId(owner, repo, 123)

// Or for comments
const commentNodeId = await toReviewCommentNodeId('1234567890', owner, repo, prNumber)

Worktree Limitations

Bare Repository Required

Efficient worktree management requires bare repository:

# First run prompts to clone
gh please issue develop 123
# Would you like to clone owner/repo as bare repository? (y/n)

Why: Multiple worktrees work best with bare repositories.

Location

Worktrees are created in:

~/.please/worktrees/{repo}/{branch}

Limitation: Cannot create worktrees in arbitrary locations via command.

Workaround: Use --checkout mode for traditional branch checkout.

Issue and PR Queries

Pagination

Large result sets require pagination:

# Only returns first 30 items by default
gh api repos/{owner}/{repo}/issues

# Use pagination
gh api repos/{owner}/{repo}/issues --paginate

Search Limits

GitHub search API has limitations:

Results limited to 1,000 items
Maximum 30 results per page
Rate limited to 30 requests per minute

Comment Operations

Edit vs Create

Edit limitations:

Can only edit your own comments
Cannot edit after certain time (varies)
Preserves comment history

Create always works:

No time restrictions
Anyone with access can create

Finding Comment IDs

Comment IDs can be found in multiple formats:

Database ID (from GitHub UI):

Issue: URL shows issuecomment-123456789
PR: URL shows discussion_r1234567890
Use the numeric part

Node ID (via CLI):

# List review threads with Node IDs
gh please pr review thread list <pr-number>

# Get comment IDs via API
gh api repos/{owner}/{repo}/issues/{number}/comments  # Issue comments
gh api repos/{owner}/{repo}/pulls/{number}/comments   # PR comments

Both formats work:

# Using Database ID (numeric from UI)
gh please pr review reply 1234567890 -b "Fixed!"

# Using Node ID (string from thread list)
gh please pr review reply PRRC_kwDOP34zbs6ShH0J -b "Fixed!"

Permissions

Required Permissions

Different operations need different permissions:

Operation	Permission
Read issues	Read
Create sub-issues	Write
Resolve threads	Write
Edit comments	Write (own) / Admin (others)

Organization Settings

Some features may be disabled by organization:

Sub-issues
Issue dependencies
Custom fields

Check: Contact your org admin if features don't work.

Workarounds

For Nested Replies

Use GitHub web UI:

github.com/{owner}/{repo}/pull/{number}#discussion_r{comment_id}

For Rate Limits

Batch operations:

# Instead of multiple calls
gh please pr review reply 111 -b "Fixed"
gh please pr review reply 222 -b "Fixed"
gh please pr review reply 333 -b "Fixed"

# Use a script
for id in 111 222 333; do
  gh please pr review reply "$id" -b "Fixed in commit abc123"
  sleep 1  # Rate limit protection
done

For Large Worktree Trees

Clean up regularly:

# Remove merged branches
gh please issue cleanup --all

Edit this pageorReport an issue

Internationalization (i18n)

Multilingual support in gh-please