gh-attach

gh-attach

gh attach uploads a file to GitHub's internal user-attachments endpoint (no public API exists) and prints the URL, which GitHub auto-renders (image/video/file) wherever it's pasted. The URL inherits the repo's visibility, so private-repo uploads stay private.

Prerequisites

Authentication: This skill requires standard gh CLI authentication. Ensure you are logged in (gh auth login) before use. Only scoped OAuth tokens (GH_TOKEN) are acceptable credential mechanisms.

⚠️ Headless/CI use: Do not use GH_ATTACH_SESSION_TOKEN (the user_session browser cookie). This cookie bypasses 2FA and is equivalent to full account takeover. It must never be passed to an unaudited third-party extension. If CI use is required, the extension must expose an OAuth-token-based authentication path upstream before this skill can be used in that context.

⚠️ Note on browser account selection: By default, gh-attach uses the account matching the active gh authentication. If the wrong browser account is selected, add --browser <name> --profile <name>. Never supply a raw user_session cookie to work around this.

The gh-attach extension must be installed and audited by a human operator before this skill is used. The operator must:

1. Review the extension source at a specific, reviewed commit SHA.
2. Install it pinned to that SHA: gh extension install sudosubin/gh-attach --pin <reviewed-commit-sha>
3. Verify the installed binary against the release artifact.
4. Re-audit before any SHA update.

The agent will never auto-install this extension. If it is absent, the skill exits with an error. Never run gh extension install autonomously within an agent session.

# Pre-installation check — the extension must be installed and audited by a human operator.
gh extension list | grep -q 'sudosubin/gh-attach' || { echo "ERROR: gh-attach extension is not installed. A human operator must install and audit it first. See Prerequisites above."; exit 1; }

Path policy: $FILE (upload source and download destination) must always resolve to a safe, expected location. The agent must never pass sensitive system paths (e.g. ~/.ssh/, ~/.config/gh/, /etc/) to any gh attach command. On download, $URL must match the github.com/user-attachments/ or GHES equivalent pattern.

Steps

1. Upload: Use an absolute quoted path. -R is optional inside a repository. For GHES, use -R host/owner/repo. The command prints the URL on one line. GitHub auto-renders it (image/video/file), so use it as-is:

# Validate $URL matches the expected GitHub user-attachments domain before uploading.
# Ensure $FILE does not point to sensitive system locations.
case "$FILE" in
  /etc/*|/proc/*|/sys/*|~/.ssh/*|~/.config/gh/*)
    echo "ERROR: $FILE is in a sensitive system location. Aborting." >&2
    exit 1
    ;;
esac

URL=$(gh attach "$FILE" -R <owner>/<repo>)

2. Embed (always --body-file -, e.g. gh pr comment/edit, gh issue comment/edit):

printf '## Screenshots\n\n%s\n' "$URL" | gh pr comment <pr> -R <owner>/<repo> --body-file -

3. Download: Specify the destination explicitly. Validate the URL before downloading. Private attachments use the active gh token:

# Validate $URL matches the expected GitHub user-attachments domain before downloading.
[[ "$URL" =~ ^https://github\.com/user-attachments/ ]] || [[ "$URL" =~ ^https://[^/]+/user-attachments/ ]] || { echo "ERROR: URL does not match expected GitHub user-attachments pattern. Aborting." >&2; exit 1; }

gh attach download "$URL" -O "$FILE"

Notes

• Private repo: URL renders only for authorized viewers. An anonymous fetch is expected to return 404 or 403.
• Sizing: embed <img width="800" src="$URL"> instead of the bare URL.
• GitHub Cloud and GHES decide which file extensions and content types they accept.