Skip to content

Epic Management

This guide covers everything you need to know about epics in Gira - from creating and organizing large initiatives to tracking progress across multiple related tickets.

Overview

Epics in Gira represent large initiatives or high-level goals that group multiple related tickets together. They help you organize work into meaningful collections and track progress toward major objectives. Each epic can contain multiple tickets and provides a way to see the bigger picture of your project's progress.

Understanding Epics

What is an Epic?

An epic is a container for related work that: - Groups multiple tickets under a common theme or goal - Tracks overall progress across all linked tickets - Provides high-level project organization - Helps with sprint planning and roadmap visualization

Epic Lifecycle

Epics typically follow this lifecycle: 1. Draft - Initial creation and planning 2. Active - Work is being done on linked tickets 3. Complete - All epic goals achieved 4. Archived - Historical record keeping

Creating Epics

Basic Epic Creation

Create a simple epic with just a title:

gira epic create "User Authentication System"

This creates an epic with: - Auto-generated ID (e.g., EPIC-001) - Default status: draft - Reporter: Current git user - Creation timestamp

Detailed Epic Creation

Create an epic with comprehensive details:

gira epic create "Mobile App Redesign" \
  --description "Complete redesign of mobile app UI/UX" \
  --owner alice@example.com \
  --target-date 2025-12-31

Epic Creation Options

  • -d, --description - Detailed description of the epic's goals
  • -o, --owner - Epic owner email (defaults to git user email)
  • --target-date - Target completion date (YYYY-MM-DD)
  • --output - Output format: text, json
  • --quiet - Only output epic ID

Best Practices for Epic Creation

  1. Use Clear, Goal-Oriented Titles: "Implement OAuth Login" not "Login Work"
  2. Write Descriptive Descriptions: Include success criteria and scope
  3. Start with Draft Status: Plan before activating
  4. Add Relevant Labels: Use consistent labeling for filtering

Viewing and Listing Epics

List All Epics

View all epics in your project:

gira epic list

This shows: - Epic ID and title - Current status - Number of linked tickets - Progress percentage - Creation date

Filtered Epic Lists

Filter epics by status: 

gira epic list --status active --status draft

Filter by owner: 

gira epic list --owner alice@example.com

Search epics: 

# Search by title or description
gira epic list --search "authentication"

# Search in specific fields
gira epic list --search "mobile" --search-in title

Epic List Options

  • -q, --query - Query expression (e.g., 'status:active AND owner:me()')
  • -s, --status - Filter by status (draft, active, completed)
  • -o, --owner - Filter by owner email
  • --search - Search text in epic fields
  • --format - Output format: table, json, yaml, csv, tsv, text, ids
  • --counts - Show summary counts

Viewing Epic Details

Show Epic Information

View complete epic details:

gira epic show EPIC-001

This displays: - Epic metadata (title, description, status, labels) - Progress information (completion percentage) - List of linked tickets with their statuses - Creation and update timestamps

Epic Show Options

  • --format - Output format: table, json, yaml, csv, tsv, text, ids
  • --json - Output as JSON (shorthand for --format json)
  • --tickets / --no-tickets - Show/hide tickets belonging to this epic

Managing Epic Content

Linking Tickets to Epics

During Ticket Creation

Link a ticket to an epic when creating it:

gira ticket create "OAuth integration" --epic EPIC-001

After Ticket Creation

Link existing tickets to an epic:

gira ticket update PROJ-123 --epic EPIC-001

Using Epic Update Command

Add multiple tickets to an epic:

gira epic update EPIC-001 --add-ticket PROJ-123 --add-ticket PROJ-124

Unlinking Tickets from Epics

Remove tickets from an epic:

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

# Remove ticket using epic command
gira epic update EPIC-001 --remove-ticket PROJ-123

Updating Epics

Update Epic Metadata

Change epic title: 

gira epic update EPIC-001 --title "Enhanced Authentication System"

Update description: 

gira epic update EPIC-001 --description "Complete OAuth and 2FA implementation"

Change status: 

gira epic update EPIC-001 --status active

Managing Epic Owner and Target Date

Update owner: 

gira epic update EPIC-001 --owner alice@example.com

Set target date: 

gira epic update EPIC-001 --target-date 2025-12-31

Epic Update Options

  • --title - New epic title
  • -d, --description - New description
  • -s, --status - New status (draft, active, completed)
  • -o, --owner - New owner email
  • --target-date - New target date (YYYY-MM-DD)
  • --add-ticket - Add ticket to epic (multiple allowed)
  • --remove-ticket - Remove ticket from epic (multiple allowed)

Epic Progress Tracking

Understanding Progress

Epic progress is automatically calculated based on linked tickets: - Completion Percentage: (Done tickets / Total tickets) × 100 - Status Summary: Count of tickets in each status - Progress Indicators: Visual representation of work completed

Viewing Progress

Check epic progress: 

gira epic show EPIC-001

View progress across all epics: 

gira epic list --sort progress --reverse

Progress Best Practices

  1. Keep Epics Focused: 5-15 tickets per epic is manageable
  2. Regular Updates: Review epic progress during sprint planning
  3. Status Alignment: Move epic to "complete" when all tickets are done
  4. Archive Old Epics: Keep active list focused on current work

Epic Workflows

Epic Planning Workflow

  1. Create Epic: Start with draft status 

    gira epic create "Q4 Performance Improvements" --status draft

  2. Plan Tickets: Break down epic into specific tickets 

    gira ticket create "Optimize database queries" --epic EPIC-002
gira ticket create "Implement caching layer" --epic EPIC-002

  3. Activate Epic: When planning is complete 

    gira epic update EPIC-002 --status active

Sprint Planning with Epics

# View epics for sprint planning
gira epic list --status active

# Check epic progress
gira epic show EPIC-002

# Add epic tickets to sprint
gira ticket list --epic EPIC-002 --status todo

Epic Completion Workflow

  1. Monitor Progress: Regular epic progress reviews
  2. Complete Epic: When all tickets are done 
    gira epic update EPIC-002 --status completed
  3. Archive Epic: Use the delete command 
    gira epic delete EPIC-002

Integration with Board and Tickets

Epic Filtering on Board

View board filtered by epic: 

gira board --epic EPIC-001

Epic-Based Reporting

List tickets by epic: 

gira ticket list --epic EPIC-001

Show epic progress summary: 

gira epic list --status active

Best Practices

Epic Organization

  1. Clear Scope: Define what's included and excluded
  2. Time-Bounded: Most epics should complete within 1-3 sprints
  3. Business Value: Each epic should deliver meaningful value
  4. Logical Grouping: Group related functionality together

Epic Management

  1. Regular Reviews: Check epic progress weekly
  2. Scope Management: Avoid epic scope creep
  3. Status Updates: Keep epic status current
  4. Documentation: Use descriptions for context and goals

Team Collaboration

  1. Shared Understanding: Ensure team understands epic goals
  2. Progress Communication: Use epics for status updates
  3. Planning Alignment: Align sprints with epic goals
  4. Retrospectives: Review epic completion and lessons learned

Common Workflows

Quarterly Planning

# Create quarterly epic
gira epic create "Q1 2025 Customer Experience" --status draft

# Plan epic content
gira ticket create "Redesign checkout flow" --epic EPIC-003
gira ticket create "Implement live chat" --epic EPIC-003

# Activate for execution
gira epic update EPIC-003 --status active

Feature Development

# Track feature development
gira epic create "Multi-language Support" --status active

# Monitor progress
gira epic show EPIC-004
gira board --epic EPIC-004

Bug Fix Initiatives

# Create bug fix epic
gira epic create "Security Vulnerability Fixes"
gira epic update EPIC-005 --status active

# Group related bugs
gira ticket update BUG-123 --epic EPIC-005
gira ticket update BUG-124 --epic EPIC-005

Troubleshooting

Common Issues

Epic not showing progress correctly - Ensure tickets are properly linked to the epic - Check that ticket statuses are up to date

Can't add ticket to epic - Verify epic ID exists: gira epic show EPIC-001 - Check ticket ID is valid: gira ticket show PROJ-123

Epic list is cluttered - Archive completed epics: gira epic update EPIC-001 --status archived - Use status filters: gira epic list --status active

Performance with Large Epics

For epics with many tickets (20+): - Consider breaking into smaller epics - Use labels for sub-categorization - Regular progress reviews to maintain focus

See Also