GitHub Issues

Manage GitHub issues end to end: list, search, view, create, label, assign, comment, close, reopen, triage, and run bulk operations. Every section leads with the gh CLI (the preferred path) and follows with a curl REST fallback for environments where gh is unavailable.

When To Use

• User asks to file, view, search, or update a GitHub issue.
• User asks to triage a backlog ("label the untriaged issues", "assign the open bugs to me").
• User asks for the status of issues on a repo ("what's open on owner/repo", "show me the bugs I'm assigned").

When NOT to Use

• Pull-request review or merge flows → not covered here; use gh pr ….
• Linear, Jira, or other trackers → use their dedicated skill.
• Plain local git history questions → answer with git log directly.

Setup

gh is the preferred path. It must be installed and authenticated before the first issue operation. Installing is non-interactive — do it yourself (it's a side-effecting command, so it runs through the approval seam; you propose it, you don't hand it to the user). Only the interactive sign-in in step 2 needs the user.

1. Install gh if it's missing

Check for it, and if it's absent, detect the platform and run the matching install command yourself:

command -v gh >/dev/null 2>&1 && echo "gh present: $(gh --version | head -1)"

If that prints nothing, install it:

brew install gh                       # macOS / Linuxbrew
sudo dnf install -y gh                # Fedora / RHEL
sudo pacman -S --noconfirm github-cli # Arch
winget install --id GitHub.cli        # Windows

Debian/Ubuntu need the GitHub CLI apt repo added first — run this chain (don't ask the user to):

(type -p wget >/dev/null || (sudo apt update && sudo apt install -y wget)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && wget -nv -O- https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg >/dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
     | sudo tee /etc/apt/sources.list.d/github-cli.list >/dev/null \
  && sudo apt update && sudo apt install -y gh

Only if the host genuinely can't install gh (no supported package manager, no sudo) fall back to the curl/REST path in step 3.

2. Authenticate gh if it isn't signed in

gh auth status >/dev/null 2>&1 && echo "gh authenticated" || echo "gh NOT authenticated"

If it's not authenticated, tell the user in one line and stop — sign-in is interactive, so they run it, not you. Say something like:

Run gh auth login in your terminal to sign in, then I can file the issue.

Pick up where you left off once they confirm; re-run gh auth status to verify before continuing.

3. Resolve the auth mode and target repo

# Prefer the gh CLI when it's present and signed in.
if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
  AUTH="gh"
else
  AUTH="curl"
  : "${GITHUB_TOKEN:?gh is unavailable — set GITHUB_TOKEN, or install and auth gh (steps 1-2)}"
fi

# Derive owner/repo from the origin remote (needed for the curl path).
OWNER_REPO=$(git remote get-url origin 2>/dev/null \
  | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=${OWNER_REPO%%/*}
REPO=${OWNER_REPO##*/}

gh reads $OWNER/$REPO from the remote automatically; pass --repo owner/repo to any gh issue command to target a different repo. For curl, the REST base is https://api.github.com/repos/$OWNER/$REPO.

1. Listing and Searching

gh:

gh issue list
gh issue list --state open --label "needs-triage" --limit 30
gh issue list --assignee @me --json number,title,labels
gh issue list --search "in:title timeout sort:created-desc"
gh issue view 128
gh issue view 128 --comments

curl:

# Open issues (the REST /issues endpoint also returns PRs — filter them out).
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues?state=open&per_page=30" \
  | jq -r '.[] | select(.pull_request|not)
           | "#\(.number)  \(.state)  \([.labels[].name]|join(","))  \(.title)"'

# A single issue with its metadata.
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128" \
  | jq -r '"#\(.number): \(.title)\nState: \(.state)  Labels: \([.labels[].name]|join(", "))\n\n\(.body)"'

# Full-text search scoped to the repo.
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/search/issues?q=timeout+in:title+repo:$OWNER/$REPO" \
  | jq -r '.items[] | "#\(.number)  \(.state)  \(.title)"'

2. Creating Issues

gh:

gh issue create \
  --title "Webhook retries drop the Idempotency-Key header" \
  --body "$(cat <<'EOF'
## Summary
Retried webhook deliveries are sent without the Idempotency-Key header,
so the downstream consumer treats each retry as a distinct event.

## Impact
Duplicate charges when a delivery is retried after a transient 5xx.

## Steps to Reproduce
1. Trigger a webhook whose first delivery returns 503.
2. Wait for the automatic retry.
3. Inspect the retried request headers.

## Expected
The retry carries the same Idempotency-Key as the original delivery.
EOF
)" \
  --label "bug,webhooks" \
  --assignee "@me"

curl:

curl -s -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues" \
  -d "$(jq -nc \
    --arg title "Webhook retries drop the Idempotency-Key header" \
    --arg body $'## Summary\nRetried deliveries omit the Idempotency-Key header.\n\n## Impact\nDuplicate charges on retry.' \
    '{title:$title, body:$body, labels:["bug","webhooks"], assignees:["octocat"]}')"

Body templates

Two fillable templates ship alongside this skill:

• templates/bug-report.md — Summary, Impact, Steps to Reproduce, Expected vs Actual, Environment, Error Output, Additional Context.
• templates/feature-request.md — Problem, Who hits this, Proposed direction, Alternatives considered, Out of scope, Additional Context.

Fill one in, then pass it straight to gh instead of inlining a heredoc. The templates sit next to this SKILL.md — under the repo at skills/dev/github-issues/templates/ for the bundled skill, or under ~/.gini/instances/<inst>/skills/dev/github-issues/templates/ for a user-installed copy.

gh issue create --title "…" --label "bug" \
  --body-file skills/dev/github-issues/templates/bug-report.md

With curl, read the file into the body field: jq -nc --arg b "$(cat templates/bug-report.md)" '{title:"…", body:$b}'. Edit the placeholders before submitting — don't file an issue with the <!-- … --> hints intact.

Attaching an image to an issue

GitHub exposes no public attachment-upload API — gh issue, REST, and GraphQL all lack an image upload, and the web drag-drop hits a private, browser-only endpoint. To embed an image, commit it to a dedicated issue-assets branch and reference its raw URL from the issue body.

1. Materialize the chat upload to disk. The upload id comes from the user message marker (Attached image uploads (in order): - <id> (<mime>, <bytes> bytes)).

   skill_run({skill: "attachments", script: "materialize", args: {uploadId: "<id-from-marker>"}}) → {path, absPath}. Use absPath below so git reads the real file regardless of the working directory.

2. Push the image to issue-assets with pure git plumbing — this never touches the working tree, index, or current branch. git commit-tree takes an explicit tree object; the parent it's given is history only and does not contribute its tree. So to add an asset to the existing branch you can't just mktree the new blob — you have to rebuild a tree that contains both the prior assets and the new one. Do that in a throwaway index (GIT_INDEX_FILE) so the real index stays untouched: seed it from the prior tip's tree, add the new blob, then write the combined tree.

   # Find the existing issue-assets tip on the remote — empty the first time,
   # before the branch exists. Don't read FETCH_HEAD instead: a failed fetch
   # leaves it pointing at an unrelated ref (e.g. the clone's default branch),
   # which would fork that whole history into the asset branch.
   PARENT=$(git ls-remote origin refs/heads/issue-assets | awk '{print $1}')
   [ -n "$PARENT" ] && git fetch origin issue-assets   # make that commit's objects local
   BLOB=$(git hash-object -w "<absPath>")
   # mktemp reserves the path; remove the empty file so git creates a fresh
   # empty index there when there's no parent to read-tree (the first asset,
   # before the issue-assets branch exists).
   TMPIDX=$(mktemp); rm -f "$TMPIDX"
   # Seed the temp index from the prior tip's tree so old assets are retained.
   [ -n "$PARENT" ] && GIT_INDEX_FILE="$TMPIDX" git read-tree "$PARENT"
   GIT_INDEX_FILE="$TMPIDX" git update-index --add --cacheinfo 100644 "$BLOB" "<filename>.png"
   TREE=$(GIT_INDEX_FILE="$TMPIDX" git write-tree)
   rm -f "$TMPIDX"
   COMMIT=$(git commit-tree "$TREE" ${PARENT:+-p "$PARENT"} -m "Add issue asset: <desc>")
   git push origin "$COMMIT":refs/heads/issue-assets

3. Verify the raw URL resolves, then reference it in the issue body:

   curl -s -o /dev/null -w '%{http_code}\n' \
     "https://raw.githubusercontent.com/$OWNER/$REPO/issue-assets/<filename>.png"
   # expect 200

   Body markdown: ![alt](https://raw.githubusercontent.com/$OWNER/$REPO/issue-assets/<filename>.png).

4. Create or comment as usual — gh issue create --body-file … / gh issue comment … (Sections 2 and 3) with that markdown in the body.

3. Managing Issues

Labels

gh:

gh issue edit 128 --add-label "priority:high" --add-label "webhooks"
gh issue edit 128 --remove-label "needs-triage"
gh label list                       # what labels exist on this repo

curl:

# Add labels.
curl -s -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128/labels" \
  -d '{"labels":["priority:high","webhooks"]}'

# Remove one label.
curl -s -X DELETE -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128/labels/needs-triage"

# List the labels defined on the repo.
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/labels?per_page=100" \
  | jq -r '.[] | "\(.name)\t\(.description // "")"'

Confirm a label exists (gh label list) before applying it — GitHub returns a generic 422 for an unknown label rather than creating it.

Assignment

gh:

gh issue edit 128 --add-assignee @me
gh issue edit 128 --add-assignee octocat --remove-assignee former-owner

curl:

curl -s -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128/assignees" \
  -d '{"assignees":["octocat"]}'

Comments

gh:

gh issue comment 128 --body "Root cause is in the retry middleware — it rebuilds the request without copying idempotency headers. Fix in progress."

curl:

curl -s -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128/comments" \
  -d "$(jq -nc --arg b "Root cause is in the retry middleware. Fix in progress." '{body:$b}')"

Closing and reopening

gh:

gh issue close 128 --reason completed --comment "Fixed in #131."
gh issue close 142 --reason "not planned"
gh issue reopen 128

curl:

# state_reason is one of: completed | not_planned | reopened
curl -s -X PATCH -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128" \
  -d '{"state":"closed","state_reason":"completed"}'

curl -s -X PATCH -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues/128" \
  -d '{"state":"open"}'

Linking issues to PRs

A PR that includes a closing keyword in its body auto-closes the issue when it merges: Closes #128, Fixes #128, or Resolves #128.

Start a branch directly from an issue:

gh issue develop 128 --checkout          # gh creates and checks out the branch
# manual equivalent:
git switch main && git pull && git switch -c fix/issue-128-idempotency-key

4. Triage Workflow

When asked to triage:

1. List the untriaged set — gh issue list --label "needs-triage" --state open.
2. Read each issue in full (gh issue view <n>) to understand whether it's a bug, a feature, or a question.
3. Apply a type + priority label and remove needs-triage (see Labels above).
4. Assign when the owner is obvious; otherwise leave it for a human.
5. Leave a short triage note as a comment when the categorization isn't self-explanatory.

5. Bulk Operations

There is no batch endpoint — loop over issue numbers client-side.

gh:

# Close every issue carrying the "wontfix" label as not-planned.
gh issue list --label "wontfix" --state open --json number --jq '.[].number' \
  | xargs -I {} gh issue close {} --reason "not planned"

curl:

curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues?labels=wontfix&state=open&per_page=100" \
  | jq -r '.[] | select(.pull_request|not) | .number' \
  | while read -r n; do
      curl -s -X PATCH -H "Authorization: Bearer $GITHUB_TOKEN" \
        "https://api.github.com/repos/$OWNER/$REPO/issues/$n" \
        -d '{"state":"closed","state_reason":"not_planned"}' >/dev/null
      echo "closed #$n"
    done

Quick Reference

Limitations

• The REST /issues collection also returns pull requests; filter with select(.pull_request|not) (curl) — gh issue already excludes them.
• Search is eventually consistent: a just-created issue may not appear in /search/issues for a few seconds. List endpoints reflect it immediately.
• No batch mutation endpoint — bulk changes loop one issue at a time and are subject to the REST secondary rate limit.
• No public attachment-upload API — embed images via the issue-assets branch + raw URL (see "Attaching an image to an issue").

Rules

1. Prefer gh when it is authenticated; only drop to curl when gh cannot be installed or authenticated. If gh is missing, install it yourself (Setup step 1) — don't ask the user to. Only the interactive gh auth login (Setup step 2) goes to the user; don't try to drive that sign-in headlessly.
2. Confirm intent before any bulk close/relabel or any single destructive change — these are side-effecting and have no undo.
3. Never put a token on a command line or in an issue/comment body; let gh use its stored credential, or pass GITHUB_TOKEN via the environment for curl.
4. Use closing keywords (Closes #N) in PR bodies rather than manually closing an issue that a merge will resolve.
5. Quote issue numbers verbatim in replies (#128) so GitHub deeplinks resolve them.