---
name: issues
description: Create and Manage issues in Gitea
dependencies: tea
---

# Issue Management

Comprehensive guide for managing Gitea issues using the tea CLI.

## Table of Contents

- [Viewing Issues](#viewing-issues)
- [Creating Issues](#creating-issues)
- [Updating Issues](#updating-issues)
- [Closing and Reopening Issues](#closing-and-reopening-issues)
- [Labels](#labels)
- [Milestones](#milestones)
- [Projects](#projects)
- [Search and Filtering](#search-and-filtering)
- [Common Workflows](#common-workflows)

## Viewing Issues

### ls issues

```bash
# 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

```bash
# 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

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

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

### Non-interactive creation

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

## Labels

### ls labels

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

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

### Create labels

```bash
# 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

```bash
# 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

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

### Manage issue labels

```bash
# 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

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

### Create milestone

```bash
# 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

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

### Delete milestone

```bash
# 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`.

```bash
# 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`.

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)
```