pr-descriptions

Use when gh pr edit --body fails silently or returns no error but doesn't persist changes - provides fallback pattern using GitHub REST API directly for reliable PR description updates

⭐21stars🔀4forks📁View on GitHub🕐Updated Jan 1, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a reliable fallback mechanism for updating GitHub Pull Request descriptions when the standard `gh pr edit` command fails silently. By utilizing the GitHub REST API directly, it ensures that PR updates are successfully persisted, even when dealing with complex multiline content, markdown formatting, and special characters that typically cause shell expansion issues.

Use Cases

  • Automating PR description updates in CI/CD pipelines where standard CLI commands fail to persist changes without throwing errors, ensuring documentation remains accurate.
  • Programmatically injecting dynamic content, such as test reports, build logs, or deployment links, into PR templates while preserving markdown formatting and backticks.
  • Developing robust developer automation scripts that require guaranteed persistence of PR metadata and verification of API responses before proceeding to subsequent workflow steps.
  • Handling complex shell environments where standard heredoc expansion might corrupt PR body content containing variables or special symbols.
namepr-descriptions
descriptionUse when gh pr edit --body fails silently or returns no error but doesn't persist changes - provides fallback pattern using GitHub REST API directly for reliable PR description updates

Updating PR Descriptions

Overview

gh pr edit --body can fail silently on some GitHub instances or configurations, accepting the command but not persisting changes. The GitHub REST API provides a reliable fallback when standard CLI tools don't work as expected.

When to Use

  • gh pr edit --body accepts command but changes don't persist (silent failure)
  • Need to programmatically update PR description with multiline content
  • Working with complex PR templates where edits aren't reflected
  • Need guaranteed persistence before moving forward

Not needed when:

  • gh pr edit --body-file successfully updates your PR
  • You only need to update title or simple fields

Core Pattern

When gh pr edit doesn't persist:

# Step 1: Get current PR details to verify number
gh pr view --json number -q '.number'

# Step 2: Try standard approach first
gh pr edit <PR_NUMBER> --body "$(cat <<'EOF'
[new body content]
EOF
)"

# Step 3: If no error but changes don't persist, use API directly
gh api repos/OWNER/REPO/pulls/<PR_NUMBER> -X PATCH -f body="$(cat <<'EOF'
[new body content]
EOF
)"

Key Pattern Elements

Use heredoc with <<'EOF' (not <<"EOF")

The single quotes prevent shell expansion:

# ✅ Correct - preserves backticks, $variables, special chars
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<'EOF'
Contains `backticks` and $special chars
EOF
)"

# ❌ Wrong - shell expands variables before API call
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<"EOF"
Contains `backticks` and $special (expands!)
EOF
)"

Get PR number if unknown

# From current branch (if tracking remote PR)
gh pr view --json number -q '.number'

Verify API call succeeded

Check the returned JSON contains your body:

gh api repos/owner/repo/pulls/123 -X PATCH -f body="new content" | grep -q "new content" && echo "Success"

Implementation

Simple Update

PR_NUMBER=$(gh pr view --json number -q '.number')

gh api repos/Reckon-Limited/reckon-frontend/pulls/$PR_NUMBER -X PATCH -f body="$(cat <<'EOF'
# Summary

This PR implements feature X.

## Features
- Feature A
- Feature B

# Testing
<!-- Testing notes -->
EOF
)"

Update with Verification

PR_NUMBER=$(gh pr view --json number -q '.number')
NEW_BODY="# Summary

This PR implements employee list actions."

gh api repos/Reckon-Limited/reckon-frontend/pulls/$PR_NUMBER -X PATCH -f body="$NEW_BODY"

# Verify by checking the returned body matches
gh pr view $PR_NUMBER --json body -q '.body' | head -1

Common Mistakes

Mistake 1: Using wrong quoting for heredoc

# ❌ Wrong - variables expand, breaks formatting
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<"EOF"
Variables like $VAR and $(commands) will expand
EOF
)"

# ✅ Correct
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<'EOF'
Variables like $VAR and $(commands) stay literal
EOF
)"

Mistake 2: Not checking return value before assuming success

# ❌ Command returns 200 but changes don't persist
gh pr edit 123 --body "new content"  # exits 0, no error

# ✅ Use API and check response
gh api repos/owner/repo/pulls/123 -X PATCH -f body="new content" | grep -q "new content"

Mistake 3: Forgetting --body-file as intermediate step

# ✅ Best practice order:
# 1. Try gh pr edit --body-file (file-based, more reliable than inline)
# 2. If that fails, use gh api (always works)
gh pr edit 123 --body-file my_body.md  # Try this first

Mistake 4: Building body string incorrectly with special chars

# ❌ Wrong - newlines lost, special chars cause issues
BODY="# Summary\nNew content"
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$BODY"

# ✅ Correct - use heredoc to preserve formatting
gh api repos/owner/repo/pulls/123 -X PATCH -f body="$(cat <<'EOF'
# Summary

New content
EOF
)"

Troubleshooting

If API call returns 422 Unprocessable Entity:

  • Check PR number is correct: gh pr view --json number
  • Check repository path (OWNER/REPO): gh api repos/Reckon-Limited/reckon-frontend --json nameWithOwner
  • Verify authentication: gh auth status

If body updates but contains escaped newlines or formatting issues:

  • Use heredoc with single quotes: <<'EOF' not <<"EOF"
  • Avoid inline strings for complex content - use heredoc

If command succeeds but gh pr view shows old body:

  • Wait a moment (GitHub API eventual consistency)
  • Clear any local cache: gh pr view --refresh
  • Verify via GitHub web UI (browser may cache)

Real-World Impact

Using the API fallback when gh pr edit silently fails ensures PR descriptions are reliably updated in automation scripts, reducing manual follow-up work and ensuring accurate PR documentation for reviewers.