walkies/.claude/skills/issues/SKILL.md

name, description, dependencies

name	description	dependencies
issues	Create and Manage issues in Gitea	tea

Issue Management

Comprehensive guide for managing Gitea issues using the tea CLI.

Table of Contents

• Viewing Issues
• Creating Issues
• Updating Issues
• Closing and Reopening Issues
• Labels
• Milestones
• Projects
• Search and Filtering
• Common Workflows

Viewing Issues

ls issues

# ls open issues in current repository
tea issue ls --repo thatguygriff/walkies

# ls all issues (open and closed)
tea issue ls --state all --repo thatguygriff/walkies

# Limit number of results
tea issue ls --limit 50 --repo thatguygriff/walkies

# Filter by label
tea issue ls --labels bug --repo thatguygriff/walkies
tea issue ls --labels "help wanted,good first issue" --repo thatguygriff/walkies

# Filter by assignee
tea issue ls --assignee @me --repo thatguygriff/walkies
tea issue ls --assignee username --repo thatguygriff/walkies

# Filter by milestone
tea issue ls --milestones "v1.0" --repo thatguygriff/walkies

# Get JSON output (use --fields to select columns)
tea issue ls --output json --fields number,title,state,labels,assignees --repo thatguygriff/walkies

View specific issue

# View issue details
tea issue view 123

# View in browser
tea issue view 123 --web

# View issue comments
tea issue view 123 --comments

# Get JSON output
tea issue view 123 --output json

Creating Issues

Interactive creation

# Create issue with interactive prompts
tea issue create --repo thatguygriff/walkies

# Follow prompts for:
# - Title
# - Body
# - Metadata (labels, assignees, milestones)

Non-interactive creation

# Create issue with title only
tea issue create --title "Fix login bug" --repo thatguygriff/walkies

# Create issue with title and body
tea issue create --title "Add dark mode" --description "Users have requested dark mode support" --repo thatguygriff/walkies

# Create issue with metadata
tea issue create \
  --title "Performance optimization" \
  --description "Optimize database queries" \
  --labels bug,performance \
  --assignees username \
  --milestone "v2.0" \
  --repo thatguygriff/walkies

Updating Issues

Edit issue

# Edit issue interactively
tea issue edit 123

# Update title
tea issue edit 123 --title "New title"

# Update body
tea issue edit 123 --description "Updated description"

# Add labels (flag is plural: --add-labels)
tea issue edit 123 --add-labels bug,priority-high

# Remove labels (flag is plural: --remove-labels)
tea issue edit 123 --remove-labels wontfix

# Add assignees (flag is plural: --add-assignees)
tea issue edit 123 --add-assignees user1,user2

# Set milestone
tea issue edit 123 --milestone "v1.5"

# Remove milestone
tea issue edit 123 --milestone ""

Comment on issue

# Add comment — body is a positional argument, not a flag
tea comment 123 "Working on this now" --repo thatguygriff/walkies

# Edit comment (requires comment ID, via API)
tea api repos/:owner/:repo/issues/comments/COMMENT_ID -X PATCH -f body="Updated comment"

Closing and Reopening Issues

# Close issue (no --comment or --reason flags available)
tea issue close 123 --repo thatguygriff/walkies

# Close multiple issues
for issue in 123 124 125; do
  tea issue close $issue --repo thatguygriff/walkies
done

# Reopen issue
tea issue reopen 123 --repo thatguygriff/walkies

# To add a comment when closing, close first then comment separately
tea issue close 123 --repo thatguygriff/walkies
tea comment 123 "Fixed in PR #456" --repo thatguygriff/walkies

Delete issues

# Delete issue (via API - CAREFUL)
tea api repos/:owner/:repo/issues/123 -X DELETE

Labels

ls labels

# ls labels in repository
tea label ls --repo thatguygriff/walkies

# Get JSON output
tea label ls --output json --repo thatguygriff/walkies

Create labels

# Create label — name is a named flag (--name), not positional
tea label create --name bug --description "Something isn't working" --color d73a4a --repo thatguygriff/walkies

# Create multiple labels
tea label create --name enhancement --description "New feature or request" --color a2eeef --repo thatguygriff/walkies
tea label create --name documentation --description "Improvements to documentation" --color 0075ca --repo thatguygriff/walkies
tea label create --name "good first issue" --description "Good for newcomers" --color 7057ff --repo thatguygriff/walkies

Update labels

# tea label edit does not exist — use tea label update with --id (get ID from tea label ls --output json)
tea label update --id 42 --name "bug" --description "Bug report" --color ff0000 --repo thatguygriff/walkies

# Rename label (change --name)
tea label update --id 42 --name new-name --repo thatguygriff/walkies

Delete labels

# Delete label by ID (get ID from tea label ls --output json)
tea label delete --id 42 --repo thatguygriff/walkies

Manage issue labels

# Add labels to issue
tea issue edit 123 --add-labels bug,priority-high --repo thatguygriff/walkies

# Remove labels from issue
tea issue edit 123 --remove-labels wontfix --repo thatguygriff/walkies

# Replace all labels (via API)
tea api repos/:owner/:repo/issues/123 -X PATCH -f labels='["bug","confirmed"]'

Milestones

ls milestones

# ls milestones (via API)
tea api repos/:owner/:repo/milestones | jq '.[] | {number: .number, title: .title, due_on: .due_on}'

Create milestone

# Create milestone
tea api repos/:owner/:repo/milestones -X POST \
  -f title="v1.0" \
  -f description="First major release" \
  -f due_on="2024-12-31T23:59:59Z"

Update milestone

# Update milestone
tea api repos/:owner/:repo/milestones/1 -X PATCH \
  -f title="v1.0.0" \
  -f state="closed"

Delete milestone

# Delete milestone
tea api repos/:owner/:repo/milestones/1 -X DELETE

Projects

Projects are managed via the API — tea issue edit does not support --add-project or --remove-project.

# ls projects (via API)
tea api repos/:owner/:repo/projects | jq '.[] | {name: .name, number: .number}'

# ls organization projects
tea api orgs/:org/projects | jq '.[] | {name: .name, number: .number}'

Search and Filtering

Search uses --keyword / -k, not --search.

# Filter by keyword in title/body
tea issue ls --keyword "authentication" --repo thatguygriff/walkies

# Filter by label + keyword
tea issue ls --labels bug --keyword "login" --repo thatguygriff/walkies

# Filter by assignee + state
tea issue ls --assignee @me --state open --repo thatguygriff/walkies

# Filter by milestone
tea issue ls --milestones "v2.0" --repo thatguygriff/walkies

# Filter by date range
tea issue ls --from "2024-01-01" --until "2024-12-31" --repo thatguygriff/walkies

Filter with JSON output

Pipe --output json to jq for advanced filtering — there is no --jq flag.

# Get open issues as JSON and filter with jq
tea issue ls --output json --repo thatguygriff/walkies \
  | jq '.[] | select(.labels[].name == "bug")'

# Count issues by label
tea issue ls --state all --output json --repo thatguygriff/walkies \
  | jq '[.[] | .labels[].name] | group_by(.) | map({label: .[0], count: length})'

# Find untriaged issues (no labels)
tea issue ls --output json --repo thatguygriff/walkies \
  | jq '.[] | select(.labels | length == 0) | {number: .number, title: .title}'

Common Workflows

Workflow 1: Bug report workflow

# Create bug report
tea issue create \
  --title "Login fails with 2FA enabled" \
  --description "$(cat <<EOF
## Bug Description
Users cannot log in when 2FA is enabled.

## Steps to Reproduce
1. Enable 2FA on account
2. Attempt to log in
3. Authentication fails

## Expected Behavior
Login should succeed with 2FA code

## Actual Behavior
Login fails with error message

## Environment
- Browser: Chrome 119
- OS: macOS 14.0
EOF
)" \
  --labels bug,priority-high \
  --assignees security-team \
  --repo thatguygriff/walkies

# Get issue number from JSON output
ISSUE=$(tea issue ls --labels bug --limit 1 --output json --repo thatguygriff/walkies | jq -r '.[0].number')

# Add follow-up comment
tea comment $ISSUE "Investigating root cause" --repo thatguygriff/walkies

# Link to PR when fixed
tea comment $ISSUE "Fixed in PR #789" --repo thatguygriff/walkies

# Close issue, then add closing comment separately
tea issue close $ISSUE --repo thatguygriff/walkies
tea comment $ISSUE "Resolved in v2.1.0" --repo thatguygriff/walkies

Workflow 2: Feature request workflow

# Create feature request
tea issue create \
  --title "Add export to PDF feature" \
  --description "Users want to export reports as PDF" \
  --labels enhancement,feature-request \
  --repo thatguygriff/walkies

# Team discusses and assigns
tea issue edit 123 --add-assignees developer1 --milestone "v2.0" --repo thatguygriff/walkies

# Track progress with comments
tea comment 123 "Starting implementation" --repo thatguygriff/walkies
tea comment 123 "UI mockups ready for review" --repo thatguygriff/walkies
tea comment 123 "Backend API complete" --repo thatguygriff/walkies

# Link to PR
tea comment 123 "Implementation complete, see PR #456" --repo thatguygriff/walkies

# Close when merged
tea issue close 123 --repo thatguygriff/walkies
tea comment 123 "Feature released in v2.0" --repo thatguygriff/walkies

Workflow 3: Issue triage workflow

# ls untriaged issues (no labels)
tea issue ls --output json --repo thatguygriff/walkies \
  | jq '.[] | select(.labels | length == 0) | {number: .number, title: .title}'

# Triage each issue (--add-labels is plural)
tea issue edit 123 --add-labels bug --repo thatguygriff/walkies
tea issue edit 124 --add-labels enhancement --repo thatguygriff/walkies
tea issue edit 125 --add-labels question,help-wanted --repo thatguygriff/walkies

# Assign priority labels
tea issue edit 123 --add-labels priority-high --repo thatguygriff/walkies
tea issue edit 124 --add-labels priority-medium --repo thatguygriff/walkies

# Assign to milestones
tea issue edit 123 --milestone "v1.5" --repo thatguygriff/walkies
tea issue edit 124 --milestone "v2.0" --repo thatguygriff/walkies

# Assign to team members
tea issue edit 123 --add-assignees developer1 --repo thatguygriff/walkies

Workflow 4: Sprint planning workflow

# ls issues in milestone
tea issue ls --milestones "Sprint 5" --output json --repo thatguygriff/walkies

# Assign issues to team members
tea issue edit 101 --add-assignees alice --repo thatguygriff/walkies
tea issue edit 102 --add-assignees bob --repo thatguygriff/walkies
tea issue edit 103 --add-assignees charlie --repo thatguygriff/walkies

# Add sprint label
for issue in 101 102 103; do
  tea issue edit $issue --add-labels "sprint-5" --repo thatguygriff/walkies
done

# Monitor progress during sprint
tea issue ls --milestones "Sprint 5" --state all --output json --repo thatguygriff/walkies

# Close completed issues
tea issue ls --milestones "Sprint 5" --labels done --output json --repo thatguygriff/walkies \
  | jq -r '.[].number' \
  | xargs -I {} tea issue close {} --repo thatguygriff/walkies

Workflow 5: Bulk issue operations

# Create multiple issues from file (title|body|labels per line)
while IFS='|' read -r title body labels; do
  tea issue create --title "$title" --description "$body" --labels "$labels" --repo thatguygriff/walkies
done < issues.txt

# Bulk close stale issues
tea issue ls --until "2023-01-01" --output json --repo thatguygriff/walkies \
  | jq -r '.[].number' \
  | xargs -I {} tea issue close {} --repo thatguygriff/walkies

# Bulk label update
tea issue ls --labels old-label --output json --repo thatguygriff/walkies \
  | jq -r '.[].number' \
  | xargs -I {} tea issue edit {} --remove-labels old-label --add-labels new-label --repo thatguygriff/walkies

# Export issues to CSV
tea issue ls --state all --output json --limit 1000 --repo thatguygriff/walkies \
  | jq -r '.[] | [.number, .title, .state, (.labels | map(.name) | join(";")), (.assignees | map(.login) | join(";")), .created] | @csv' \
  > issues.csv

Tips and Best Practices

1. Label systematically: Develop a consistent labeling scheme
2. Triage regularly: Review and label new issues promptly
3. Link PRs: Always reference issues in PR descriptions
4. Use milestones: Group related issues for release planning
5. Assign clearly: Assign issues to specific people
6. Comment updates: Keep stakeholders informed with comments
7. Use --output json + jq: Combine for powerful filtering and reporting
8. Get label IDs first: tea label update and tea label delete require --id, not name — run tea label ls --output json to find IDs

Quick Reference

# List
tea issue ls                                           # ls open issues
tea issue ls --state all                               # ls all issues
tea issue ls --labels bug                              # Filter by label (plural flag)
tea issue ls --assignee @me                            # Your issues
tea issue ls --keyword "auth"                          # Search by keyword

# View
tea issue view 123                                     # View issue details
tea issue view 123 --web                               # Open in browser
tea issue view 123 --comments                          # Include comments

# Create
tea issue create                                       # Interactive creation
tea issue create --title "text" --description "text"   # Non-interactive
tea issue create --labels bug --assignees user         # With metadata (both plural)

# Update
tea issue edit 123 --title "new title"                 # Change title
tea issue edit 123 --add-labels bug                    # Add label (plural flag)
tea issue edit 123 --remove-labels wontfix             # Remove label (plural flag)
tea issue edit 123 --add-assignees user                # Add assignee (plural flag)

# Comment (tea comment, not tea issue comment)
tea comment 123 "comment text" --repo thatguygriff/walkies

# Close/Reopen (no --comment or --reason flags; add comment separately)
tea issue close 123                                    # Close issue
tea issue reopen 123                                   # Reopen issue

# Labels
tea label ls                                           # ls labels
tea label create --name "bug" --color d73a4a           # Create (--name flag required)
tea label update --id 42 --name new-name               # Update (--id required, not name)
tea label delete --id 42                               # Delete (--id required, not name)