TrackerJo/github-pr-attachments

GitHub PR attachments

GitHub itself is the approved host for BuildPurdue PR screenshots and recordings. This skill turns ignored local evidence into GitHub-hosted PR attachments without committing media to the repository.

Use this skill after visual-proof captures evidence and before a user-visible PR is called ready.

Preconditions

1. Confirm the evidence files exist and are under ignored artifacts/.
2. Confirm GitHub CLI is authenticated for this repository with gh auth status.
3. Confirm the installed CLI supports attachments by checking the relevant command help, for example gh pr edit --help, for --attach.
4. Confirm the target PR and latest pushed commit are the ones being proved.

Do not infer attachment support from the gh version string when the command itself can answer directly.

Preferred workflow: body with embedded evidence

When screenshots need captions, before/after tables, or a specific order, write the PR body to an ignored local Markdown file and reference the local media paths normally:

## Visual evidence

| Before | After |
| --- | --- |
| ![Before: mobile event page](artifacts/event-before-phone.png) | ![After: mobile event page](artifacts/event-after-phone.png) |

[Interaction recording](artifacts/event-flow.mp4)

Then publish the body and attach every referenced media file in the same command:

gh pr edit <pr> \
  --body-file artifacts/pr-body.md \
  --attach artifacts/event-before-phone.png \
  --attach artifacts/event-after-phone.png \
  --attach artifacts/event-flow.mp4

GitHub CLI uploads the files and rewrites matching local Markdown references to the resulting GitHub-hosted attachment URLs. This is preferred over manually pasting URLs because the body remains readable before upload and GitHub owns the final URLs.

Append-only evidence

When layout does not matter, an image or video can be appended without replacing the PR body:

gh pr edit <pr> --attach 'artifacts/after.png#After: corrected mobile layout'

Repeat --attach for multiple files. Use useful alt text for screenshots. Videos do not take alt text.

For an evidence comment instead of the PR body:

gh pr comment <pr> \
  --body-file artifacts/evidence-comment.md \
  --attach artifacts/after.png \
  --attach artifacts/interaction.mp4

Verify publication

Treat the command exit code and the PR itself as separate checks. GitHub can successfully upload some files while another attachment fails.

After every upload:

1. Check the command exit status.
2. Re-read the PR body or comment from GitHub.
3. Confirm every required local path was replaced by a GitHub-hosted URL.
4. Confirm there are no duplicate appended attachments caused by a mismatched local Markdown path.
5. Open the posted media from the PR when the active harness supports it.
6. Confirm the media proves the latest pushed commit and contains no secrets, tokens, personal data, email addresses, OTPs, or unrelated user content.

If any required attachment is missing or stale, the PR is not ready.

Hard restrictions

• Never commit PR-only screenshots or recordings. Do not add .github/pr-assets/, public/pr-assets/, docs media, or another tracked asset directory just to make evidence linkable.
• Never use a third-party file host for BuildPurdue PR evidence unless the user explicitly approves that host for the specific case.
• Never invent, predict, or hand-construct attachment URLs. Only use URLs returned or written by GitHub.
• Never weaken the visual-proof requirement because upload tooling is missing. If --attach is unavailable, report that exact prerequisite and keep the PR not-ready.
• Never publish sensitive captures. Redact or recapture before upload.
• Keep local evidence in artifacts/; it is intentionally gitignored and can be deleted after GitHub-hosted evidence is verified.

Why this exists

This follows the same operating rule as T3 Code: user-visible changes carry reviewable visual evidence, that evidence is uploaded to GitHub, and PR-only screenshots are never committed to product history.

GitHub's CLI attachment feature behaves like browser paste/drop: it uploads the image or video to GitHub and inserts the hosted URL into the PR or comment.

Sources

• T3 Code contributor rules: https://github.com/pingdotgg/t3code/blob/main/AGENTS.md
• GitHub CLI attachment documentation: https://docs.github.com/en/github-cli/github-cli/attaching-files-with-github-cli
• gh pr edit --attach manual: https://cli.github.com/manual/gh_pr_edit

Source

Edit this copy under .agents/skills/. The pre-commit hook mirrors it into .claude/skills/; do not edit the mirror directly.