git-issue-manage

## When to Use This Skill | Use this skill when... | Use the alternative when... | |---|---| | Transferring, pinning, locking, or bulk-editing GitHub issues | Use `github-issue-writing` to compose a single issue body well | | Creating a development branch from an issue (`gh issue develop`) | Use `git-branch-pr-workflow` for general branch + PR design | | Updating custom issue fields (priority, severity, custom selects) in bulk | Use `github-labels` for label-only operations on issues and PRs | | Performing bulk operations across many issue numbers in one command | Use `git-triage` to evaluate issues and PRs by completion evidence and CI state | ## Context - Git remotes: !`git remote -v` Open issues are fetched during execution (requires a configured git remote). ## Parameters Parse `$ARGUMENTS[0]` as the operation, remaining args as issue numbers and options. Issue references accept bare numbers, `#N`, or full GitHub issue URLs (`https://github.com/<owner>/<repo>/issues/<N>`): strip a leading `#`, and for a URL extract the trailing `/issues/<N>` number (require trailing digits — a `/pull/<N>` is not an issue). When a URL's `<owner>/<repo>` differs from the current remote, pass `-R <owner>/<repo>` to the `gh` calls for that issue. | Operation | Syntax | Description | |-----------|--------|-------------| | `transfer` | `transfer <N> <target-repo>` | Transfer issue to another repository | | `pin` | `pin <N...>` | Pin issues to repository (max 3) | | `unpin` | `unpin <N...>` | Unpin issues | | `lock` | `lock <N...> [--reason <reason>]` | Lock issue discussions | | `unlock` | `unlock <N...>` | Unlock issue discussions | | `develop` | `develop <N> [--branch <name>] [--checkout]` | Create branch from issue | | `bulk` | `bulk <sub-op> <N...> [options]` | Bulk operations on multiple issues | | `fields` | `fields <N> [--set <field>=<value>] [--list]` | Manage custom issue fields | Lock reasons: `off-topic`, `too heated`, `resolved`, `spam` Bulk sub-operations: `label`, `assign`, `close`, `reopen` ## When to Use | Use this skill when... | Use X instead when... | |------------------------|----------------------| | Transferring issues between repos | Creating new issues (`github-issue-writing`) | | Pinning/unpinning important issues | Implementing issue fixes (`git:issue`) | | Locking resolved discussions | Managing sub-issues/deps (`git:issue-hierarchy`) | | Creating dev branches from issues | Searching for issues (`github-issue-search`) | | Bulk labeling/assigning/closing | Auto-detecting related issues (`github-issue-autodetect`) | | Setting custom field values | | ## Execution Execute the requested issue management operation. ### Step 1: Parse Operation and Validate Parse the operation from `$ARGUMENTS[0]`. Validate that specified issue numbers exist: ```bash gh issue view $N --json number,title,state 2>/dev/null ``` If any issue is not found, report it and skip that issue. ### Step 2: Execute Operation #### Transfer Transfer an issue to another repository within the same organization or owner. ```bash gh issue transfer $N $TARGET_REPO ``` **Prerequisites:** - Target repo must exist and you must have write access - Both repos must be owned by the same user/org (or target accepts transfers) Report the new issue URL after transfer. #### Pin / Unpin Pin important issues to the top of the issues list (maximum 3 pinned per repo). ```bash # Pin gh issue pin $N # Unpin gh issue unpin $N ``` If pinning would exceed the 3-pin limit, report which issues are currently pinned and ask which to unpin. #### Lock / Unlock Lock issue threads to prevent further comments. ```bash # Lock with reason gh issue lock $N --reason resolved # Lock without reason gh issue lock $N # Unlock gh issue unlock $N ``` | Reason | When to use | |--------|-------------| | `resolved` | Issue is fixed, no further discussion needed | | `off-topic` | Discussion has drifted from the issue | | `too heated` | Discussion has become unproductive | | `spam` | Issue thread contains spam | #### Develop Create a development branch linked to the issue. ```bash # Create branch and switch to it locally gh issue develop $N --checkout # Create branch with custom name gh issue develop $N --name $BRANCH_NAME --checkout # Create branch without checkout gh issue develop $N ``` The branch name defaults to `{issue-number}-{issue-title-slug}`. The branch is automatically linked to the issue on GitHub. #### Bulk Operations Apply the same operation to multiple issues at once. **Bulk label:** ```bash # Pre-check: create any missing labels before applying for LABEL in $(echo "$LABELS" | tr ',' '\n'); do if ! gh label list --search "$LABEL" --json name | jq -e ".[] | select(.name==\"$LABEL\")" >/dev/null 2>&1; then echo "Label '$LABEL' not found — skipping (create it first with: gh label create \"$LABEL\")" LABELS=$(echo "$LABELS" | sed "s/,$LABEL//;s/$LABEL,//;s/^$LABEL$//") fi done for N in $ISSUE_NUMBERS; do [ -n "$LABELS" ] && gh issue edit $N --add-label "$LABELS" done ``` **Bulk assign:** ```bash for N in $ISSUE_NUMBERS; do gh issue edit $N --add-assignee "$USERS" done ``` **Bulk close:** ```bash for N in $ISSUE_NUMBERS; do gh issue close $N done ``` **Bulk reopen:** ```bash for N in $ISSUE_NUMBERS; do gh issue reopen $N done ``` Report success/failure count after bulk operations. #### Custom Fields Manage custom issue fields (requires org-level issue field configuration). **List available fields:** ```bash # Get org name from repo ORG=$(gh repo view --json owner --jq '.owner.login') # List fields gh api orgs/$ORG/issue-fields --jq '.[] | "\(.id): \(.name) (\(.type))"' ``` **Get field values for an issue:** ```bash gh api repos/$OWNER/$REPO/issues/$N/issue-field-values \ --jq '.[] | "\(.field.name): \(.value)"' ``` **Set a field value:** ```bash FIELD_ID=$(gh api orgs/$ORG/issue-fields --jq '.[] | select(.name == "$FIELD_NAME") | .id') gh api repos/$OWNER/$REPO/issues/$N/issue-field-values \ -X POST -f field_id=$FIELD_ID -f value="$VALUE" ``` If the repo is not in an organization, report: "Custom issue fields require an organization-level repository." ### Step 3: Report Results | Operation | Report | |-----------|--------| | `transfer` | New issue URL in target repo | | `pin/unpin` | Confirmation, current pinned issues list | | `lock/unlock` | Confirmation with lock reason | | `develop` | Branch name and URL, checkout status | | `bulk` | Success/failure count per issue | | `fields` | Field values table or confirmation of update | ## Error Handling | Error | Cause | Action | |-------|-------|--------| | `unknown command "develop"` | Older `gh` CLI version | Report: "gh issue develop requires gh CLI 2.30+. Update with: gh upgrade" | | 403 on transfer | No write access to target | Report permission requirement | | 422 on pin | Already 3 pinned issues | List current pins, ask which to replace | | 404 on issue-fields | Org doesn't have custom fields | Report: "Custom fields not configured for this organization" | ## Agentic Optimizations | Context | Command | |---------|---------| | Transfer issue | `gh issue transfer N target-repo` | | Pin issue | `gh issue pin N` | | Lock issue | `gh issue lock N --reason resolved` | | Create dev branch | `gh issue develop N --checkout` | | Bulk close | Loop: `gh issue close N` for each N | | List custom fields | `gh api orgs/{org}/issue-fields --jq '.[].name'` | | Get field values | `gh api repos/{o}/{r}/issues/N/issue-field-values` | ## See Also - **git:issue-hierarchy** skill for sub-issues and dependencies - **github-issue-writing** skill for creating new issues - **git:issue** skill for implementing/processing issues - **gh-cli-agentic** skill for raw API command patterns - [REFERENCE.md](REFERENCE.md) for custom fields API details