DOCSEARCHbyAlgolia
Submit Docs

gh-pr-review

repository·main·Indexed 41 days ago

https://github.com/agynio/gh-pr-review

A GitHub CLI extension providing terminal-based access to inline PR review comments and threads. It features structured, compact GraphQL-based JSON output designed to be LLM-friendly, allowing users to start, manage, and submit reviews, reply to threads, and resolve discussions via the command line.

Tokens
10K
Snippets
42
Records
44
Agent score
52%

What's inside gh-pr-review

  1. Understand the JSON output format

    main

    All commands return structured JSON optimized for programmatic use. Key characteristics include:

    • Consistent field names and stable ordering.
    • Omitted fields instead of null values.
    • Pre-joined thread replies.
    • Essential data only (no URLs or metadata noise).

    ID Formats:

    • Reviews: PRR_...
    • Threads: PRRT_...
    • Comment Nodes: PRRC_... (available via --include-comment-node-id)
    {
  "reviews": [
    {
      "id": "PRR_...",
      "state": "CHANGES_REQUESTED",
      "author_login": "reviewer",
      "comments": [
        {
          "thread_id": "PRRT_...",
          "path": "src/file.go",
          "author_login": "reviewer",
          "body": "Consider refactoring this",
          "created_at": "2024-01-15T10:30:00Z",
          "is_resolved": false,
          "is_outdated": false,
          "thread_comments": [
            {
              "author_login": "author",
              "body": "Good point, will fix",
              "created_at": "2024-01-15T11:00:00Z"
            }
          ]
        }
      ]
    }
  ]
}

  2. Install gh-pr-review as an AI Agent skill

    main

    You can add gh-pr-review as a reusable skill for AI coding agents using the npx skills add command. This registers the extension and its commands as skill actions for the agent.

    # Install to a specific agent
npx skills add agynio/gh-pr-review -a claude-code

# Install globally
npx skills add agynio/gh-pr-review -g

  3. Create and submit a PR review

    main

    The review process follows a three-step workflow: start a pending review, add inline comments, and finally submit the review with an event type.

    # 1. Start a pending review
gh pr-review review --start -R owner/repo <pr-number>

# 2. Add inline comments (repeat as needed)
gh pr-review review --add-comment \
  --review-id <PRR_...> \
  --path <file-path> \
  --line <line-number> \
  --body "Your comment" \
  -R owner/repo <pr-number>

# 3. Submit the review
gh pr-review review --submit \
  --review-id <PRR_...> \
  --event <APPROVE|REQUEST_CHANGES|COMMENT> \
  --body "Overall review summary" \
  -R owner/repo <pr-number>

  5. Run tests and linters for development

    main

    When developing locally, run the test suite and linters with CGO_ENABLED=0 to ensure the environment matches the release build configuration.

    CGO_ENABLED=0 go test ./...
CGO_ENABLED=0 golangci-lint run

  6. Select a pull request for commands

    main

    All gh pr-review commands accept pull request selectors in two ways:

    1. A full URL: https://github.com/owner/repo/pull/123
    2. A PR number combined with the -R flag: -R owner/repo 123

    Unless otherwise specified, commands emit JSON output. Optional fields are omitted from the JSON rather than being serialized as null. Array responses default to [].

    # Example of using the -R shorthand
gh pr-review <command> -R owner/repo 42

  7. Install or upgrade gh-pr-review

    main

    Install the gh-pr-review GitHub CLI extension using the gh extension install command. To update an existing installation to the latest version, use the upgrade command.

    gh extension install agynio/gh-pr-review
# Update an existing installation
gh extension upgrade agynio/gh-pr-review

  8. View review snapshots with `review view`

    main

    Use review view to get a consolidated snapshot of reviews, inline comments, and replies. This is the recommended way to discover metadata like thread_id or comment_node_id before performing mutations like replying or resolving.

    Filters:

    • --reviewer: Filter by a specific reviewer.
    • --states: Filter by review states (e.g., CHANGES_REQUESTED).
    • --unresolved: Show only unresolved threads.
    • --not_outdated: Show only threads that are not outdated.
    • --tail: Show only the latest replies.
    • --include-comment-node-id: Decorates parent comments and replies with their GraphQL comment_node_id fields.

    Backend: GitHub GraphQL pullRequest.reviews query.

    gh pr-review review view --reviewer octocat --states CHANGES_REQUESTED -R owner/repo 42

  10. Submit a pending review

    main

    Finalize a pending review using gh pr-review review --submit. You must reuse the original PRR_... identifier with the --review-id flag and specify a review event (e.g., REQUEST_CHANGES) using the --event flag.

    gh pr-review review --submit \
  --review-id PRR_kwDOAAABbcdEFG12 \
  --event REQUEST_CHANGES \
  --body "Please add tests" \
  -R owner/repo 42

  11. Resolve or unresolve threads with `threads resolve` / `threads unresolve`

    main

    Use threads resolve to mark a review thread as resolved, or threads unresolve to reopen it.

    Requirements:

    • --thread-id (required): The GraphQL review thread node ID (e.g., PRRT_...).

    Backend: GitHub GraphQL resolveReviewThread or unresolveReviewThread mutations.

    Output Schema: Returns a ThreadMutationResult object containing thread_node_id and is_resolved (boolean).

    gh pr-review threads resolve --thread-id R_ywDoABC123 -R owner/repo 42