github-comment-body-file-safety

name	github-comment-body-file-safety
description	Prevent shell-quoting and command-substitution bugs when posting GitHub issue/PR comments or editing bodies with gh CLI.
version	1.0.0
author	Hermes Agent
license	MIT
triggers	["When using `gh issue comment`, `gh pr comment`, `gh issue edit --body`, `gh pr edit --body`, or `gh issue create --body`","When comment/body text contains backticks, code spans, file paths, markdown, or dynamic content","When a GitHub comment/body is being assembled from plan paths, test names, or command output"]
tags	["github","gh","shell-safety","comments","quoting"]

GitHub Comment Body-File Safety

Problem

Inline gh ... --body "..." looks convenient, but shell parsing happens before GitHub CLI sees the text. If the body contains backticks, $(), code fences, or other shell-significant characters, the shell can:

• execute unintended commands
• strip or mangle content
• turn file paths into failing shell commands
• post broken comments

This happened in live use when a GitHub comment included markdown code spans like docs/plans/... and tests/... inline; the shell tried to execute those paths.

Rule

If the body contains any markdown/code formatting or dynamic content, use --body-file. Do not use inline --body.

Safe pattern

cat > /tmp/gh-comment.md <<'EOF'
Planning update:

- Draft saved at `docs/plans/2026-04-20-issue-2419-skill-markdown-contract-drift.md`
- Index updated in `docs/plans/README.md`
- Next check: `uv run pytest tests/skills/test_repo_skill_parity_merges.py -q`
EOF

gh issue comment 2419 --body-file /tmp/gh-comment.md

Also use the same pattern for:

• gh pr comment ... --body-file
• gh issue edit ... --body-file
• gh pr edit ... --body-file
• gh issue create ... --body-file

Important: this is not just a comment/edit problem. gh issue create --body "..." is equally vulnerable. In live use, an inline create body containing markdown code spans caused bash to try executing repo paths and run IDs, producing a malformed issue body. The safe recovery was to rewrite the intended issue body to a temp markdown file and run gh issue edit --body-file ....

When body-file is mandatory

Use --body-file if the text includes:

• backticks: `...`
• command substitutions: $()
• fenced code blocks
• file paths or commands copied from plans/tests
• multiline markdown
• text generated from tools/scripts
• any user-provided content you did not fully hand-escape

Recovery pattern

If an inline comment/body was already posted and looks mangled:

1. write the intended text to a temp markdown file
2. re-post or edit using --body-file
3. for malformed new issues created via gh issue create --body, immediately repair the issue with gh issue edit --body-file <file>
4. verify the rendered GitHub comment/body afterward

Heredoc pitfall: Python generators still need quoted delimiters

Do not embed markdown with backticks inside an unquoted shell heredoc, even if the heredoc feeds Python instead of cat. Bash performs command substitution before Python runs:

# BAD: backticks inside the Python string are executed by bash first
python3 - <<PY
body = "Plan: `docs/plans/example.md`"
PY

Use a quoted heredoc delimiter, pass dynamic values through environment variables or argv, and then post with --body-file:

SHA="$sha" FULL="$full" python3 - <<'PY'
from pathlib import Path
import os
body = f"Plan: `docs/plans/example.md`\nCommit: `{os.environ['SHA']}` (`{os.environ['FULL']}`)\n"
Path('/tmp/gh-comment.md').write_text(body)
PY

gh issue comment 123 --body-file /tmp/gh-comment.md

Minimal checklist

Before any gh ... --body call, ask:

1. Does this text contain backticks or markdown? If yes, use --body-file.
2. Was any part of this text produced dynamically? If yes, use --body-file.
3. Do I want exact rendering with zero shell interpretation? If yes, use --body-file.

Bottom line

--body-file is the safe default. Inline --body is only for truly simple, shell-safe one-liners.