Initialization & Configuration¶

This guide covers how to initialize a Gira project and configure it for your team's workflow.

Quick Start¶

Initialize a new Gira project in your Git repository:

gira init "My Project"

This creates a .gira/ directory with: - Project configuration - Default board structure - Ticket storage directories

The `gira init` Command¶

Basic Usage¶

gira init <project-name>

Arguments: - project-name - Name of your project (required)

Options: - --prefix - Custom ticket ID prefix (default: first 4 letters of project name in uppercase) - --strict-workflow - Use traditional linear workflow instead of flexible transitions - --workflow - Choose workflow template: scrum, kanban, support-desk, bug-tracking, minimal, custom (default: interactive selection) - --non-interactive / --no-input - Run without prompts (useful for CI/CD and automation) - --description - Project description - --force - Overwrite existing project

Examples¶

# Initialize with default prefix
gira init "Web Application"
# Creates tickets like: WEBA-1, WEBA-2

# Initialize with custom prefix  
gira init "Mobile App" --prefix MOB
# Creates tickets like: MOB-1, MOB-2

# Initialize with strict workflow
gira init "Enterprise App" --prefix ENT --strict-workflow
# Enforces linear ticket progression

# Non-interactive mode for automation
gira init "CI Project" --non-interactive --prefix CIP --workflow minimal
# No prompts, uses provided values or defaults

# Non-interactive with all options
gira init "Automated Project" \
  --non-interactive \
  --prefix AUTO \
  --workflow kanban \
  --description "Project created by CI/CD pipeline"

What Gets Created¶

The initialization creates this structure:

.gira/
├── config.json       # Project configuration
├── board.json        # Board and swimlane setup
├── .state.json      # Internal state tracking
├── backlog/         # Backlog tickets
├── board/           # Active tickets by status
│   ├── todo/
│   ├── in_progress/
│   ├── review/
│   └── done/
├── epics/           # Epic definitions (future)
├── sprints/         # Sprint data (future)
│   ├── active/
│   └── completed/
└── archive/         # Completed tickets (future)

Workflow Types¶

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

Flexible Workflow (Default)¶

The flexible workflow is designed for agile teams that need flexibility:

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

Features: - Skip stages (e.g., backlog → in_progress, skipping todo) - Move tickets directly from in_progress → done (skip review) - Reopen done tickets to any previous status - Move from review back to todo

Best for: - Small, collaborative teams - Rapid prototyping projects - Teams with varying ticket complexity - Projects that value flexibility over process

Strict Workflow¶

The strict workflow enforces traditional linear progression:

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

Features: - Must progress through each stage sequentially - Cannot skip stages (must go through review before done) - Done tickets can only be reopened to backlog - More predictable and auditable ticket flow

Best for: - Larger teams requiring consistency - Compliance-driven projects - Teams with formal review processes - Projects requiring clear audit trails

Configuration Files¶

config.json¶

Main project configuration:

{
  "project": {
    "name": "My Project",
    "prefix": "PROJ",
    "created_at": "2024-01-15T10:30:00Z",
    "default_assignee": null,
    "strict_workflow": false
  }
}

Fields: - name - Project display name - prefix - Ticket ID prefix (2-4 uppercase letters) - created_at - Project creation timestamp - default_assignee - Optional default assignee email - strict_workflow - Whether to use strict linear workflow (default: false)

.board.json¶

Kanban board configuration (created based on workflow type):

Flexible Workflow (default):

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

Strict Workflow (with --strict-workflow):

{
  "swimlanes": [
    {"id": "backlog", "name": "Backlog"},
    {"id": "todo", "name": "To Do"},
    {"id": "in_progress", "name": "In Progress", "limit": 3},
    {"id": "review", "name": "Review", "limit": 2},
    {"id": "done", "name": "Done"}
  ],
  "transitions": {
    "backlog": ["todo"],  // Must go through todo
    "todo": ["in_progress", "backlog"],
    "in_progress": ["review", "todo", "backlog"],  // Must go through review
    "review": ["done", "in_progress"],
    "done": ["backlog"]  // Can only reopen to backlog
  }
}

Customizable: - Add/remove swimlanes - Set WIP limits per swimlane - Define workflow transitions

.state.json¶

Internal state (auto-managed):

{
  "next_id": 1
}

Tracks the next ticket ID to assign.

Version Control¶

By default, the .gira/ directory is tracked in Git. This allows: - Team collaboration on tickets - History of all changes - Branching workflows

To exclude from Git:

echo ".gira/" >> .gitignore

Customizing Your Workflow¶

Adding Swimlanes¶

Edit .gira/board.json to add custom swimlanes:

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

Setting WIP Limits¶

Enforce Work-In-Progress limits:

{
  "id": "in_progress",
  "name": "In Progress",
  "limit": 3  // Maximum 3 tickets
}

Defining Transitions¶

Control allowed status changes:

{
  "transitions": {
    "todo": ["in_progress"],
    "in_progress": ["qa", "todo"], 
    "qa": ["staging", "in_progress"],
    "staging": ["done", "qa"],
    "done": ["todo"]
  }
}

Non-Interactive Mode¶

For CI/CD pipelines, automation scripts, or AI assistants, Gira supports non-interactive initialization:

Using the Flag¶

# Basic non-interactive mode
gira init "My Project" --non-interactive

# With all options specified
gira init "My Project" \
  --non-interactive \
  --prefix PROJ \
  --workflow minimal \
  --description "Automated setup"

Environment Variables¶

Gira automatically enables non-interactive mode when these environment variables are set: - CI - Standard CI environment variable - GIRA_NON_INTERACTIVE - Gira-specific flag

# Using environment variable
export GIRA_NON_INTERACTIVE=1
gira init "My Project"  # No prompts

# In CI/CD pipelines (CI variable is usually set automatically)
gira init "My Project"  # No prompts

Default Values¶

In non-interactive mode: - Prefix: Auto-generated from project name (first 2-4 letters) - Workflow: custom (most flexible) - Description: Empty string

Requirements¶

When using --non-interactive: - Project name must be provided as argument - Invalid options will cause immediate failure - No prompts will be shown for any reason

Environment Variables¶

Optional environment variables:

GIRA_DEFAULT_ASSIGNEE - Default assignee for new tickets
EDITOR - Text editor for editing descriptions
CI - Enables non-interactive mode automatically
GIRA_NON_INTERACTIVE - Forces non-interactive mode

Reinitializing¶

To reset a project:

# Remove existing Gira data
rm -rf .gira/

# Reinitialize
gira init "My Project"

⚠️ Warning: This deletes all tickets and configuration!

Working with Multiple Projects¶

Gira detects the project by looking for .gira/ in the current directory or parent directories (like Git).

# Project A
cd ~/projects/web-app
gira init "Web App"

# Project B  
cd ~/projects/mobile-app
gira init "Mobile App"

# Each has separate tickets and configuration

Migrating Between Versions¶

Future versions will include migration tools. For now: 1. Export tickets to JSON 2. Update Gira 3. Reinitialize project 4. Import tickets

Common Issues¶

"Not a Gira project"¶

Run commands from within a Gira project directory:

cd /path/to/project
gira ticket list

Permission Errors¶

Ensure you have write access to create .gira/:

# Check permissions
ls -la

# Fix if needed
sudo chown -R $(whoami) .

Invalid Configuration¶

If config.json or board.json become corrupted:

Check JSON syntax
Restore from Git history
Or reinitialize project

Best Practices¶

Choose Meaningful Prefixes: Use 3-4 letter abbreviations
Set Realistic WIP Limits: Start with team size +1
Review Transitions: Match your actual workflow
Document Custom Fields: If you extend the schema
Regular Backups: Commit .gira/ changes frequently

Next Steps¶

After initialization:

Initialization & Configuration¶

Quick Start¶

The gira init Command¶

Basic Usage¶

Examples¶

What Gets Created¶

Workflow Types¶

Flexible Workflow (Default)¶

Strict Workflow¶

Configuration Files¶

config.json¶

.board.json¶

.state.json¶

Version Control¶

Customizing Your Workflow¶

Adding Swimlanes¶

Setting WIP Limits¶

Defining Transitions¶

Non-Interactive Mode¶

Using the Flag¶

Environment Variables¶

Default Values¶

Requirements¶

Environment Variables¶

Reinitializing¶

Working with Multiple Projects¶

Migrating Between Versions¶

Common Issues¶

"Not a Gira project"¶

Permission Errors¶

Invalid Configuration¶

Best Practices¶

Next Steps¶

See Also¶

The `gira init` Command¶