github-attachments

Attach a screenshot, image, mockup, diagram, log file, JSON/trace dump, or any binary artifact to a GitHub PR or issue, or share one inline instead of as a gist. Use whenever a PR/issue comment, descr

SKILL.md

GitHub

Attach files to GitHub PRs and issues

Use gh attach, the GitHub CLI extension installed by this dotfiles repo, when a PR or issue needs an image or file such as a screenshot, mockup, log, or trace. PR and issue uploads live on auth-protected refs under refs/uploads/issues/<N>; ad-hoc uploads use refs/uploads/misc/<key>.

Choose an upload

  • Use a PR or issue upload when an image belongs in a PR/issue description or comment: for example, a UI change, repro screenshot, before/after view, or design mockup.
  • Use an ad-hoc upload for a small artifact you want to share inline, such as a log snippet, JSON dump, or captured trace.
  • Prefer an inline attachment over a gist or external host when the artifact belongs with the GitHub discussion.

Upload and share

By default, gh attach prints Markdown to stdout; it does not post a comment unless --comment is set.

gh attach <pr-or-issue> path/to/file.png
gh attach path/to/file.png
gh attach --comment <pr> screenshot.png
gh attach --title "<label>" <pr> file.png
gh attach --key <slug> banner.png

The first command prints a Markdown image tag for you to paste. The second detects the PR from the current branch. Put flags before the PR/issue number when using --title. --key creates an ad-hoc upload that is not tied to a PR or issue.

For scripts, request JSON and extract the uploaded file URL:

gh attach --json <pr> file.png | jq -r '.files[0].url'

On success, --json suppresses stderr; failures still print a plain-text error to stderr.

You can pipe a screenshot from macOS or insert the generated Markdown into a longer PR comment:

screencapture -i -t png - | gh attach --name shot.png <pr> -
gh attach <pr> file.png | gh pr comment <pr> --body-file -

When reading from stdin, --name is required.

Inspect or restore uploads

gh attach list
gh attach list --issues
gh attach list --misc
gh attach get <pr> --output ./restored

list shows every upload ref in the current repository; --issues and --misc filter the results. get restores the PR's uploaded files to the given output directory.

Clean up

To purge PR and issue upload refs automatically when a PR or issue closes, copy .github/workflows/cleanup-gh-attach.yml from the upstream repository into the target repository's .github/workflows/. The workflow handles only refs/uploads/issues/*.

Ad-hoc uploads under refs/uploads/misc/* are not garbage-collected. Delete one manually with confirmation disabled:

gh attach delete --key <slug> --yes

--yes is required for non-interactive use, including agent-driven invocations.

Agent-specific checks

  • To verify an upload in a private repository, use gh api repos/<owner>/<name>/contents/<file>?ref=<sha>. The embed URL blob/<sha>/<file>?raw=true requires a browser session cookie; a PAT does not authenticate it.
  • Before deleting an ad-hoc upload, include --yes. Without it, the command waits for confirmation and can hang an agent run.