Ticket Management¶

This guide covers all ticket-related operations in Gira, from creating and updating tickets to managing their lifecycle.

Overview¶

Tickets are the fundamental unit of work in Gira. Each ticket represents a task, bug, feature, or other work item that needs to be tracked. Tickets are stored as JSON files in the .gira/ directory and can be moved between different statuses as work progresses.

Creating Tickets¶

Basic Creation¶

Create a new ticket with just a title:

gira ticket create "Fix login bug"

This creates a ticket with: - Auto-generated ID (e.g., PROJ-1) - Default type: task - Default priority: medium - Default status: todo - Reporter: Current git user

Advanced Creation¶

Create a ticket with specific attributes:

gira ticket create "Implement OAuth login" \
  --type feature \
  --priority high \
  --description "Add support for Google and GitHub OAuth" \
  --assignee alice@example.com \
  --labels api,authentication

All Creation Options¶

-d, --description - Detailed description
-t, --type - Type: story, task, bug, epic, feature, subtask
-p, --priority - Priority: low, medium, high, critical
-s, --status - Initial status: backlog, todo, in_progress, review, done
-a, --assignee - Assignee email address
--epic - Link to epic ID
--parent - Parent ticket ID (for subtasks)
-l, --labels - Comma-separated labels

Listing Tickets¶

Basic List¶

View all tickets:

gira ticket list

Filtered Lists¶

List tickets by status:

gira ticket list -s todo -s in_progress

List high-priority bugs:

gira ticket list -t bug -p high -p critical

List your tickets:

gira ticket list --assignee "$(git config user.email)"

List unassigned tickets:

gira ticket list --assignee ""

Sorting and Limiting¶

# Sort by priority (highest first)
gira ticket list --sort priority --reverse

# Show only first 10 tickets
gira ticket list --limit 10

# Show ticket counts by status
gira ticket list --counts

All List Options¶

-s, --status - Filter by status (multiple allowed)
-t, --type - Filter by type (multiple allowed)
-p, --priority - Filter by priority (multiple allowed)
-a, --assignee - Filter by assignee
--assignee "$(git config user.email)" - Show only your tickets
--assignee "" - Show only unassigned tickets
--epic - Filter by epic ID
-l, --label - Filter by label (multiple allowed)
--sort - Sort by: created, updated, priority, status
--reverse - Reverse sort order
--limit - Maximum tickets to show
--show-empty - Show empty swimlanes
--counts - Show only counts

Viewing Ticket Details¶

View complete ticket information:

gira ticket show PROJ-123

This displays: - All ticket metadata - Full description - Labels and relationships - Creation and update timestamps - Related epic (if linked)

Updating Tickets¶

Update Single Field¶

# Change priority
gira ticket update PROJ-123 --priority critical

# Reassign ticket
gira ticket update PROJ-123 --assignee bob@example.com

# Update title
gira ticket update PROJ-123 --title "New title"

Update Multiple Fields¶

gira ticket update PROJ-123 \
  --type bug \
  --priority high \
  --description "Updated description"

Managing Labels¶

# Add labels
gira ticket update PROJ-123 --add-label backend --add-label urgent

# Remove labels
gira ticket update PROJ-123 --remove-label wontfix

Managing Relationships¶

# Link to epic
gira ticket update PROJ-123 --epic EPIC-001

# Add blocking relationship
gira ticket update PROJ-123 --add-blocked-by PROJ-122

# Remove blocker
gira ticket update PROJ-123 --remove-blocked-by PROJ-122

Unassigning¶

# Remove assignee
gira ticket update PROJ-123 --assignee none

# Unlink from epic
gira ticket update PROJ-123 --epic none

All Update Options¶

--title - New title
-d, --description - New description
-t, --type - New type
-p, --priority - New priority
-s, --status - New status
-a, --assignee - New assignee (use "none" to unassign)
--epic - Epic ID (use "none" to unlink)
--add-label - Add label (multiple allowed)
--remove-label - Remove label (multiple allowed)
--add-blocked-by - Add blocker (multiple allowed)
--remove-blocked-by - Remove blocker (multiple allowed)

Moving Tickets¶

Move Between Statuses¶

Move tickets through the workflow:

# Start work on a ticket
gira ticket move PROJ-123 in_progress

# Move to review
gira ticket move PROJ-123 review

# Mark as done
gira ticket move PROJ-123 done

# Move back to backlog
gira ticket move PROJ-123 backlog

Workflow Transitions¶

Gira enforces valid workflow transitions: - From todo → in_progress - From in_progress → review or back to todo - From review → done or back to in_progress - From done → back to todo (reopening)

Special case: Any ticket can be moved to backlog.

Force Move¶

Skip transition validation:

gira ticket move PROJ-123 done --force

Ticket Ordering¶

Gira supports manual ordering of tickets within their status columns/swimlanes. This allows you to prioritize work visually on the board and maintain a custom order that reflects your workflow needs.

Understanding Ticket Order¶

Column-specific: Ordering only affects tickets within the same status
Persistent: Order is maintained across sessions and synced via Git
Visual: Order is reflected in gira board and gira ticket list outputs
Flexible: Use position numbers or relative placement

Position-Based Ordering¶

Use numeric positions to place tickets exactly where you want:

# Move ticket to top of column (position 1)
gira ticket order PROJ-123 1

# Move to third position
gira ticket order PROJ-123 3

# Move to end of column (use large number)
gira ticket order PROJ-123 999

Position Rules: - Positions start at 1 (not 0) - If position > number of tickets, ticket moves to end - Other tickets shift to accommodate the new position

Relative Ordering¶

Place tickets relative to other tickets:

# Place PROJ-123 before PROJ-456
gira ticket order PROJ-123 --before PROJ-456

# Place PROJ-123 after PROJ-789
gira ticket order PROJ-123 --after PROJ-789

Relative Rules: - Reference ticket must be in the same status - Clear error messages if reference ticket not found - Cannot combine with position argument

Viewing Ticket Order¶

See tickets in their current order:

# Visual board with ordered columns
gira board

# List tickets for specific status (ordered)
gira ticket list --status todo

# Show all tickets grouped by status (ordered within groups)
gira ticket list

Ordering Best Practices¶

Top Priority at Top: Keep most important work at position 1
Group Related Work: Place related tickets near each other
Regular Grooming: Reorder during sprint planning or daily standups
Consistent Strategy: Team should agree on ordering criteria

Common Ordering Workflows¶

Sprint Planning¶

# List backlog items
gira ticket list -s backlog

# Move high-priority items to top
gira ticket order PROJ-101 1
gira ticket order PROJ-102 2
gira ticket order PROJ-103 3

# Move planned items to todo in priority order
gira ticket move PROJ-101 todo
gira ticket move PROJ-102 todo
gira ticket move PROJ-103 todo

Daily Prioritization¶

# View current todo items
gira board

# Reprioritize based on new information
gira ticket order URGENT-999 1
gira ticket order PROJ-123 --after PROJ-456

Epic-Based Ordering¶

# Find all tickets in an epic
gira query "epic:EPIC-001" --format ids > epic-tickets.txt

# Order them together in todo column
cat epic-tickets.txt | while read id; do
  gira ticket order $id --after EPIC-MARKER-001
done

Technical Details¶

Order Values: Internally uses numeric values with gaps for insertions
Auto-rebalancing: System automatically rebalances when gaps are exhausted
Default Order: New tickets have order=0 and appear at bottom
Stable Sorting: Tickets with same order value sort by ID

Troubleshooting¶

"Position must be >= 1" - Use position 1 or higher, not 0

"Can only specify one of: position, --before, --after" - Choose either position number OR relative placement, not both

"Ticket X not found in Y status" - Reference ticket must be in same status for relative ordering

Tickets not appearing in expected order - Check if tickets have explicit order: gira ticket show PROJ-123 - Tickets with order=0 appear at bottom - Use gira ticket order to set explicit order

Bulk Operations with Ticket ID Streaming¶

Gira supports processing multiple tickets by reading ticket IDs from stdin. This enables powerful pipeline operations for bulk ticket management.

Basic Ticket ID Streaming¶

Use - as the ticket ID to read from stdin:

# Move multiple tickets to a new status
echo -e "PROJ-1\nPROJ-2\nPROJ-3" | gira ticket move - in_progress

# Update multiple tickets with the same changes
cat ticket-list.txt | gira ticket update - --priority high --add-labels urgent

# Archive multiple tickets at once
echo -e "OLD-1\nOLD-2" | gira ticket delete - --force

Pipeline Operations with Query¶

Combine the query command with ticket operations for powerful workflows:

# Move all high-priority bugs to in-progress
gira query "priority:high AND type:bug" --format ids | gira ticket move - in_progress

# Add labels to tickets in a specific epic
gira query "epic:EPIC-001" --format ids | gira ticket update - --add-labels security

# Archive all done tickets older than 30 days
gira query "status:done AND updated:<30d" --format ids | gira ticket delete - --force

Output Formats¶

Control output when processing multiple tickets:

# Quiet mode - only show ticket IDs
cat ticket-list.txt | gira ticket move - done --quiet

# JSON output for scripting
echo -e "PROJ-1\nPROJ-2" | gira ticket update - --status review --output json

Error Handling¶

Operations continue even if some tickets fail:

# Process valid tickets, report failures
echo -e "VALID-1\nINVALID-999\nVALID-2" | gira ticket move - done
# Output: Total: 3, Successful: 2, Failed: 1

Ticket Storage¶

Tickets are stored in directories based on their status:

.gira/
├── backlog/          # Backlog tickets
├── board/            # Active tickets
│   ├── todo/
│   ├── in_progress/
│   ├── review/
│   └── done/
└── archive/          # Completed tickets (future)

Each ticket is a JSON file named with its ID (e.g., PROJ-123.json).

Best Practices¶

Use Descriptive Titles: Make titles searchable and clear
Set Appropriate Types: Use bug for defects, feature for new functionality
Prioritize Correctly: Reserve critical for blocking issues
Add Descriptions: Provide context for complex tickets
Use Labels: Organize tickets with consistent labels
Link Related Work: Use epics and parent tickets for organization
Keep Status Current: Move tickets as work progresses

Tips and Tricks¶

Quick Assignment: Use --assignee "$(git config user.email)" to see your work
Bulk Updates: Update multiple fields in one command
Status Overview: Use --counts for quick status summary
Keyboard Shortcuts: Most options have short forms (e.g., -p for --priority)
JSON Output: Add --json to any command for scripting

Common Workflows¶

Bug Triage¶

# List all bugs
gira ticket list -t bug

# Find critical bugs
gira ticket list -t bug -p critical -p high

# Assign bug to developer
gira ticket update BUG-123 -a developer@example.com

Sprint Planning¶

# List backlog items
gira ticket list -s backlog

# Move tickets to sprint
gira ticket move PROJ-123 todo
gira ticket move PROJ-124 todo

Daily Standup¶

# Show your in-progress work
gira ticket list --assignee "$(git config user.email)" -s in_progress

# Show blocked tickets
gira ticket list --label blocked

Ticket Management¶

Overview¶

Creating Tickets¶

Basic Creation¶

Advanced Creation¶

All Creation Options¶

Listing Tickets¶

Basic List¶

Filtered Lists¶

Sorting and Limiting¶

All List Options¶

Viewing Ticket Details¶

Updating Tickets¶

Update Single Field¶

Update Multiple Fields¶

Managing Labels¶

Managing Relationships¶

Unassigning¶

All Update Options¶

Moving Tickets¶

Move Between Statuses¶

Workflow Transitions¶

Force Move¶

Ticket Ordering¶

Understanding Ticket Order¶

Position-Based Ordering¶

Relative Ordering¶

Viewing Ticket Order¶

Ordering Best Practices¶

Common Ordering Workflows¶

Sprint Planning¶

Daily Prioritization¶

Epic-Based Ordering¶

Technical Details¶

Troubleshooting¶

Bulk Operations with Ticket ID Streaming¶

Basic Ticket ID Streaming¶

Pipeline Operations with Query¶

Output Formats¶

Error Handling¶

Ticket Storage¶

Best Practices¶

Tips and Tricks¶

Common Workflows¶

Bug Triage¶

Sprint Planning¶

Daily Standup¶

See Also¶