attach-assets

Files (1)

• SKILL.md

SKILL.md (first lines)

# Attach Assets

Copies one or more local files onto a dedicated **orphan branch** in the repository via a throwaway git worktree, then embeds them in a GitHub issue or PR as a comment (default) or appended to the description body.
The files never land on the default branch and never become inline `user-attachments`, which suits sensitive screenshots, logs, and internal diagrams.

Because the branch is orphan (no shared history with `main`) and the files are placed through a temporary worktree, the user's working branch and tree are left untouched.
The assets are still in git history on that branch, so they are visible to everyone with read access to the repo and persist until the branch is deleted and history rewritten; do not use this for material that must never enter the repo at all (use signed expiring object-store URLs for that).

## Prerequisites

- The command runs inside a working clone of the target repository.
- `git` with push access to the repository.
- `gh` CLI authenticated with write access, for posting the comment or patching the description body.
- Files must be under GitHub's per-file size limit (roughly 100 MB), since they are committed through ordinary git.
- A target issue or PR.
  Provide a full GitHub URL for unambiguous parsing, or a bare number with `--pr` / `--issue` (default) using the current repository.
- For private repos, the rendered image is visible to collaborators when viewed in the issue or PR, but the raw URL itself requires a token for a direct fetch.

## Skill attribution (GitHub)

Before posting the comment or patching the body, read [`github-post-attribution/SKILL.md`](../github-post-attribution/SKILL.md) and append the **Posted with** footer for `SKILL_DIR` = `attach-assets` to the posted body.

## Path scheme

Each upload is written to the orphan branch under a directory named after the issue or PR number.
GitHub issues and PRs share one number sequence, so the number alone is unambiguous:

```
<number>/<filename>
```

If the same filename is uploaded twice to the same number, the second upload overwrites the first on the branch; give the file a distinct name instead.

## Workflow

```
Parse target ref -> (REPO, KIND=issues|pulls, NUMBER)
             |
             v
Verify files exist
             |
             v
Add a throwaway worktree on orphan branch `assets`
(existing branch checked out; new branch created empty with --orphan)
             |
             v
Copy files into <NUMBER>/ and git add + commit
             |
             v
Push to origin <ASSET_BRANCH>, then remove the worktree
             |
             v
Build markdown (image vs. link per extension)
             |
             v
Attach: comment (default) or append to body (--to-body)
             |
             v
Print raw URLs + branch paths
```

## Steps

### 1. Parse the target reference

```bash
TARGET="$1"; shift
FILES=("$@")
ASSET_BRANCH="${ASSET_BRANCH:-assets}"   # override via --branch <name>
MODE="comment"                            # --to-body switches this to "body"
KIND_DEFAULT="issues"                     # --pr switches to "pulls"
# Parse --pr / --issue / --to-body / --branch out of FILES as needed.
```

Resolve `REPO`, `KIND`, `NUMBER`:

```bash
case "$TARGET" in
  *github.com*)
    REPO=$(printf '%s' "$TARGET" | sed -E 's#https?://github.com/([^/]+/[^/]+)(/.*)?#\1#')
    KIND=$(printf '%s' "$TARGET" | grep -oE '/(issues|pull)/' | tr -d '/' | sed 's#^pull$#pulls#')
    NUMBER=$(printf '%s' "$TARGET" | grep -oE '/(issues|pull)/[0-9]+' | grep -oE '[0-9]+$')
    ;;
  *)
    REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
    NUMBER="$TARGET"
    KIND="$KIND_DEFAULT"
    ;;
esac
```

`KIND` is only used to choose the body endpoint; the asset path uses `NUMBER` alone.

### 2. Verify the files

```bash
for f in "${FILES[@]}"; do
  [ -f "$f" ] || { echo "::error::not a file: $f"; exit 1; }
done
```

### 3. Stage a temporary worktree on the orphan branch

```bash
STAGE=$(mktemp -d)
if git ls-remote --exit-code --heads origin "$ASSET_BRANCH" >/dev/null 2>&1; then
  git fetch origin "$ASSET_BRANCH" --quiet
  git worktree add --detach --quiet "$STAGE" "origin/$ASSET_BRANCH" >/dev/null
else
  git worktree add --no-checkout --detach --quiet "$STAGE" >/dev/null
  git -C "$STAGE" checkout --orphan "$ASSET_BRANCH" >/dev/null
  git -C "$STAGE" read-tree --empty          # start the orphan with no staged files
fi
```

The worktree isolates all work from the user's current branch.
On an existing asset branch the asset tree is checked out so new files sit beside prior uploads; on a new branch an empty orphan is created (no shared history with `main`).

### 4. Place the files, commit, and push

From tomzx/agents, MIT.

More from tomzx/agents