Skip to content

Kanban Workflow Guide

This guide explains how to use Gira with a Kanban workflow for your project.

📋 Kanban Overview

Kanban is a visual workflow management method that helps teams visualize work, limit work-in-progress, and maximize efficiency. Gira provides a kanban board to manage your development flow.

Typical Board Configuration

  • Columns: Todo, In Progress, Review, Done
  • Optional Columns: Blocked, Testing, Staging
  • WIP Limits: Can be configured per column

🔄 Workflow States

1. Todo (Backlog)

  • New tickets start here
  • Prioritized list of work items
  • No work has begun

Actions: 

# Create new ticket in todo
gira ticket create "Feature description" --priority medium

# View todo items
gira board --columns todo

2. In Progress (Active Work)

  • Work actively being done
  • Should have an assignee
  • Consider setting a WIP limit

Actions: 

# Move ticket to in progress
gira ticket move TICKET-ID "in progress"

# Assign to yourself
gira ticket update TICKET-ID --assignee me

# View work in progress
gira board --columns "in progress"

3. Review (Quality Check)

  • Work completed, awaiting review
  • Code review, testing, or approval needed
  • Consider setting a WIP limit

Actions: 

# Move to review
gira ticket move TICKET-ID review

# Add review comment
gira comment add TICKET-ID --message "Ready for review: [PR link]"

4. Done (Completed)

  • Work fully completed and deployed
  • No further action needed
  • Can be archived periodically

Actions: 

# Mark as done
gira ticket move TICKET-ID done

# View completed work
gira ticket list --status done

5. Blocked (Optional)

  • Work cannot proceed due to dependencies
  • Requires action to unblock
  • Should have blocking reason in comments

Actions: 

# Mark as blocked
gira ticket move TICKET-ID blocked

# Add blocking reason
gira comment add TICKET-ID --message "Blocked: waiting for API access"

📊 Kanban Metrics

Work In Progress (WIP)

Current WIP across columns: 

# Check current WIP
gira board --show-counts

# List over-limit columns
gira board --check-wip

Cycle Time

Average time from "In Progress" to "Done": 

# View cycle time report
gira report cycle-time --days 30

Throughput

Number of items completed per week: 

# View throughput
gira report throughput --weeks 4

🎯 Best Practices

1. Respect WIP Limits

  • Don't exceed column limits
  • Finish work before starting new items
  • Help blocked items before taking new work

2. Pull, Don't Push

  • Pull work when you have capacity
  • Don't assign work to others
  • Let team members choose their tasks

3. Make Work Visible

# Update ticket regularly
gira ticket update TICKET-ID --description "Progress: 60% complete"

# Add blockers immediately
gira comment add TICKET-ID --message "Blocked: need design approval"

4. Focus on Flow

  • Move tickets promptly when state changes
  • Don't let tickets stagnate
  • Address bottlenecks quickly

🚀 Daily Workflow

Morning Standup

# View board state
gira board

# Check blocked items
gira ticket list --status blocked

# Review your items
gira ticket list --assignee me

During the Day

# When starting work
gira ticket move TICKET-ID "in progress"
gira ticket update TICKET-ID --assignee me

# When blocked
gira ticket move TICKET-ID blocked
gira comment add TICKET-ID  # Explain blockage

# When ready for review
gira ticket move TICKET-ID review

End of Day

# Update progress
gira ticket update TICKET-ID --description "Today's progress..."

# Check tomorrow's work
gira board --columns todo --limit 5

📈 Continuous Improvement

Weekly Metrics Review

# Generate weekly report
gira report weekly

# Analyze bottlenecks
gira report bottlenecks --days 7

# Review cycle times
gira report cycle-time --by-type

Retrospective Actions

  1. Review completed tickets
  2. Identify process improvements
  3. Adjust WIP limits if needed
  4. Update workflow documentation

🔧 Customizing Your Kanban

Adjust WIP Limits

# Set WIP limit for column
gira config set workflow.wip.in_progress 5
gira config set workflow.wip.review 3

Add Custom Columns

# Add new column
gira config set workflow.columns "todo,in progress,testing,review,done"

Set Up Automation

# Auto-assign on move to in progress
gira config set workflow.auto_assign true

# Auto-move to done on PR merge
gira config set workflow.github_integration true

🚨 Common Issues

WIP Limit Exceeded

# Find over-limit columns
gira board --check-wip

# List items in column
gira ticket list --status "in progress"

# Move items back or forward
gira ticket move TICKET-ID review

Stagnant Tickets

# Find old in-progress items
gira ticket list --status "in progress" --older-than 7d

# Add update or move
gira comment add TICKET-ID
gira ticket move TICKET-ID blocked

Unclear Priorities

# Review and update priorities
gira ticket list --status todo --sort priority

# Reprioritize
gira ticket update TICKET-ID --priority high

📚 Kanban Resources

  • "Kanban: Successful Evolutionary Change for Your Technology Business" - David J. Anderson
  • "Making Work Visible" - Dominica DeGrandis

Common Integrations

  • GitHub/GitLab: Link PRs to tickets
  • CI/CD: Auto-update ticket status
  • Slack: Notifications for ticket changes

🎓 Kanban Principles

  1. Visualize the Workflow - Use gira board
  2. Limit WIP - Respect column limits
  3. Manage Flow - Monitor cycle time
  4. Make Policies Explicit - Document your process
  5. Implement Feedback Loops - Regular reviews
  6. Improve Collaboratively - Team retrospectives

Workflow type: Kanban