Board Management¶

The board command provides a visual kanban-style view of your tickets, organized by status in swimlanes. This guide covers how to use and customize the board view.

Overview¶

The Gira board displays tickets in columns representing different stages of work. Each column (swimlane) can have a Work-In-Progress (WIP) limit to help maintain flow and identify bottlenecks.

Basic Usage¶

Display the Board¶

View all tickets on the board:

gira board

This shows: - All swimlanes (To Do, In Progress, Review, Done) - Tickets in each swimlane with ID, title, type, priority, and assignee - WIP limit indicators when limits are exceeded - Color-coded priorities and types

Compact View¶

For boards with many tickets or long titles:

gira board --compact

This truncates long titles to fit better on screen.

Filtering the Board¶

By Assignee¶

View tickets for a specific person:

# Show tickets assigned to alice
gira board --assignee alice@example.com

# Show your tickets
gira board --assignee "$(git config user.email)"

By Type¶

Filter by ticket type:

# Show only bugs
gira board --type bug

# Show features and stories
gira board --type feature --type story

By Priority¶

Filter by priority level:

# Show high priority items
gira board --priority high --priority critical

# Show only critical issues
gira board -p critical

By Label¶

Filter by labels:

# Show tickets with 'backend' label
gira board --label backend

# Show tickets with multiple labels
gira board -l api -l urgent

By Epic¶

Show tickets for a specific epic:

gira board --epic EPIC-001

Combined Filters¶

Combine multiple filters:

# Critical bugs assigned to me
gira board --assignee "$(git config user.email)" -t bug -p critical

# High priority backend tasks
gira board -p high -l backend -t task

Board Configuration¶

The board is configured in .gira/.board.json:

{
  "swimlanes": [
    {
      "id": "backlog",
      "name": "Backlog"
    },
    {
      "id": "todo",
      "name": "To Do",
      "limit": 10
    },
    {
      "id": "in_progress", 
      "name": "In Progress",
      "limit": 3
    },
    {
      "id": "review",
      "name": "Review", 
      "limit": 2
    },
    {
      "id": "done",
      "name": "Done"
    }
  ],
  "transitions": {
    "backlog": ["todo", "in_progress"],
    "todo": ["in_progress", "backlog"],
    "in_progress": ["review", "done", "todo", "backlog"],
    "review": ["done", "in_progress", "todo"],
    "done": ["backlog", "todo", "in_progress"]
  }
}

Swimlanes¶

Each swimlane has: - id - Internal identifier matching ticket status - name - Display name shown on board - limit - Optional WIP limit

Transitions¶

Defines allowed movements between swimlanes. Used by gira ticket move to enforce workflow.

Workflow Types¶

Gira supports two workflow types that can be configured during project initialization:

Flexible Workflow (Default)¶

The flexible workflow allows teams to skip stages and move tickets more freely:

# Initialize with flexible workflow (default)
gira init "My Project" --prefix PROJ

Features: - Skip from backlog directly to in_progress - Move from in_progress directly to done (skipping review) - Reopen done tickets to any previous status - Move from review back to todo

This workflow is ideal for: - Small teams with high trust - Rapid prototyping - Projects with varying ticket complexity - Teams that need flexibility

Strict Workflow¶

The strict workflow enforces traditional linear progression:

# Initialize with strict workflow
gira init "My Project" --prefix PROJ --strict-workflow

Features: - Must move through each stage sequentially - Cannot skip stages (e.g., must go through review before done) - Done tickets can only be reopened to backlog - More predictable ticket flow

This workflow is ideal for: - Larger teams needing consistency - Compliance-driven projects - Teams with formal review processes - Projects requiring audit trails

WIP Limits¶

Work-In-Progress limits help maintain flow:

When a swimlane exceeds its limit, the count appears in red
WIP indicators are automatically shown when limits are exceeded
WIP limits are configured per swimlane in board.json

Example with WIP limit exceeded:

┌─────────────────────────┬─────────────────────────┬─────────────────────────┐
│ To Do (5)               │ In Progress (4/3) ⚠️    │ Review (1/2)            │
├─────────────────────────┼─────────────────────────┼─────────────────────────┤
│ PROJ-123 Fix bug        │ PROJ-124 New feature    │ PROJ-130 API docs       │
│ PROJ-125 Update docs    │ PROJ-126 Refactor code  │                         │
│ ...                     │ PROJ-127 Write tests    │                         │
│                         │ PROJ-128 Security fix   │                         │
└─────────────────────────┴─────────────────────────┴─────────────────────────┘

Visual Indicators¶

The board uses colors and symbols for quick scanning:

Priority Colors¶

🔴 Critical - Red, urgent issues
🟠 High - Yellow/Orange, important tasks
🟢 Medium - Green, normal priority
⚪ Low - Dim/Gray, lower priority

Type Indicators¶

🐛 Bug - Defects and issues
✨ Feature - New functionality
📋 Task - General work items
📖 Story - User stories
🎯 Epic - Large initiatives
📌 Subtask - Part of larger ticket

Status Symbols¶

⚠️ WIP Limit Exceeded - Too many items in swimlane
👤 Assigned - Shows assignee email
🏷️ Labels - Tagged with labels

Board Command Options¶

All available options:

-a, --assignee - Filter by assignee email
--assignee "$(git config user.email)" - Show only your tickets
-t, --type - Filter by type (multiple allowed)
-p, --priority - Filter by priority (multiple allowed)
-l, --label - Filter by label (multiple allowed)
--epic - Filter by epic ID
-c, --compact - Truncate long titles

Common Workflows¶

Daily Standup¶

# Show team's in-progress work
gira board

# Show just your items
gira board --assignee "$(git config user.email)"

Sprint Review¶

# Show completed items
gira ticket list -s done

# Show items still in progress
gira ticket list -s in_progress -s review

Identifying Blockers¶

# Show high-priority items not started
gira ticket list -s todo -p high -p critical

# Show items stuck in review
gira ticket list -s review --sort created

Team Load Balancing¶

# Check each team member's load
gira board -a alice@example.com
gira board -a bob@example.com

# Find unassigned work
gira ticket list --assignee "" -s todo

Tips and Tricks¶

Monitor WIP Limits: Keep swimlanes within limits for better flow
Use Compact Mode: Great for standup meetings on projectors
Filter by Epic: Track progress on major initiatives
Combine Filters: Zero in on specific work items
Regular Reviews: Check the board daily to spot bottlenecks

Customizing the Board¶

To modify swimlanes or transitions:

Edit .gira/board.json
Add/remove swimlanes as needed
Update transition rules
Adjust WIP limits based on team capacity

Example: Add a "QA" swimlane:

{
  "swimlanes": [
    {"id": "todo", "name": "To Do", "limit": 10},
    {"id": "in_progress", "name": "In Progress", "limit": 3},
    {"id": "qa", "name": "QA Testing", "limit": 2},
    {"id": "review", "name": "Code Review", "limit": 2},
    {"id": "done", "name": "Done"}
  ],
  "transitions": {
    "todo": ["in_progress"],
    "in_progress": ["qa", "todo"],
    "qa": ["review", "in_progress"],
    "review": ["done", "qa"],
    "done": ["todo"]
  }
}

Integration with Other Commands¶

The board works seamlessly with other Gira commands:

# Create a ticket and see it on the board
gira ticket create "New feature" -s todo
gira board

# Move ticket and watch it change columns  
gira ticket move PROJ-123 in_progress
gira board

# Update ticket and see changes reflected
gira ticket update PROJ-123 -p critical
gira board