Skip to content

Extensions

Extend Gira's functionality with the powerful hook system and custom integrations.

🎯 What are Extensions?

Gira's extensibility system allows you to: - Automate workflows with event-driven hooks and HTTP webhooks - Integrate external tools like Slack, Jira, CI/CD systems - Custom notifications and reporting - Enforce project policies and validation rules - Build custom workflows that fit your team's needs

🔧 Extensibility Systems

Gira provides two complementary extensibility systems:

🔗 HTTP Webhooks

Send real-time event data to external services via HTTP. Perfect for: - Team notifications (Slack, Discord, Teams) - External integrations (Jira, GitHub, CI/CD) - Cloud automation (Zapier, serverless functions) - Monitoring and analytics (custom dashboards, metrics)

🪝 Local Hook System

Run custom scripts locally in response to events. Ideal for: - File system operations (git commands, file management) - Local validation (code quality checks, policy enforcement) - Project-specific automation (environment setup, documentation) - Fast, synchronous operations (immediate feedback)

✨ Key Features

Both Systems: - Event-Driven: Automatically trigger on Gira events - Rich Data: Access comprehensive event data - Configurable: Project-level control with timeouts and error handling - Safe: Built-in timeout protection and error isolation

Webhooks: - HTTP Delivery: Reliable delivery with retry logic - Service Templates: Pre-built integrations for popular services - Advanced Filtering: Query-based event filtering - Authentication: Bearer, API Key, Basic Auth support - Monitoring: Health checks and delivery statistics

Local Hooks: - Multi-Language: Write in Bash, Python, Ruby, JavaScript, or any executable - Environment Variables: Direct access to event data - Fast Execution: Minimal overhead with efficient execution

🚀 Quick Start

HTTP Webhooks

# Add Slack webhook
gira webhook add slack https://hooks.slack.com/services/... --template slack

# Add filtered webhook
gira webhook add alerts https://api.example.com/webhook --filter "priority:high"

# Test and monitor
gira webhook test slack
gira webhook health

Local Hooks

# Initialize hooks directory with templates
gira ext init

# List available hooks
gira ext list

# Test a hook
gira ext test ticket-created

# Enable/disable hook system
gira ext enable
gira ext disable

📖 Documentation

🎨 Available Hook Types

Hook Triggered When Use Cases
ticket-created New ticket is created Notifications, auto-assignment, validation
ticket-updated Ticket is modified Change logging, external sync, approvals
ticket-moved Ticket status changes Workflow automation, git operations
sprint-completed Sprint is marked complete Reports, metrics, team notifications

💡 Common Use Cases

🔔 Notifications

  • Webhooks: Slack/Discord/Teams notifications, email alerts, dashboard updates
  • Local Hooks: Console notifications, desktop alerts, log file updates

🔄 Automation

  • Webhooks: External system sync, CI/CD triggers, cloud automation
  • Local Hooks: Git operations, file management, environment setup

📊 Reporting & Analytics

  • Webhooks: Metrics collection, external dashboards, business intelligence
  • Local Hooks: Local reports, CSV exports, project statistics

🛡️ Governance

  • Webhooks: External approval workflows, compliance reporting
  • Local Hooks: Code quality checks, naming conventions, local validation

🌟 Integration Examples

Webhook: Slack Notifications

# Simple setup with template
gira webhook add slack https://hooks.slack.com/services/T00/B00/XXX --template slack

# Custom webhook for critical issues
gira webhook add critical-slack https://hooks.slack.com/services/T00/B00/XXX \
  --filter "priority:critical OR type:bug" \
  --template slack

Local Hook: Git Branch Creation

#!/bin/bash
# .gira/hooks/ticket-created.sh

# Create feature branch when ticket is created
git checkout -b "feature/$GIRA_TICKET_ID" 2>/dev/null || true
echo "Created feature branch: feature/$GIRA_TICKET_ID"

Combined: Webhook + Hook

# Webhook notifies team (external)
gira webhook add team-slack https://hooks.slack.com/... --template slack

# Hook creates branch (local)
# .gira/hooks/ticket-created.sh does git operations

Both systems work together for comprehensive automation!

⚙️ Configuration

Both systems are configured in .gira/config.json:

Webhook Configuration

# Global webhook settings
gira config set webhooks.enabled true
gira config set webhooks.timeout 30
gira config set webhooks.retry_attempts 3

# Individual webhooks configured via CLI
gira webhook add <name> <url> [options]

Hook Configuration

# Local hook settings
gira config set hooks.enabled true
gira config set hooks.timeout 60
gira config set hooks.on_failure warn
gira config set hooks.silent false

🔍 Environment Variables

Hooks receive rich event data via environment variables:

GIRA_ROOT=/path/to/project
GIRA_HOOKS_DIR=/path/to/project/.gira/hooks
GIRA_TICKET_ID=GCM-123
GIRA_TICKET_TITLE=Fix authentication bug
GIRA_TICKET_STATUS=in_progress
GIRA_TICKET_TYPE=bug
GIRA_TICKET_PRIORITY=high
GIRA_TICKET_ASSIGNEE=dev@example.com
# ... and many more

🏗️ Future Extensions

Both extensibility systems provide the foundation for additional features:

  • Plugin Architecture: Installable plugins for common integrations
  • Custom Commands: Add your own gira subcommands
  • Advanced Webhooks: OAuth 2.0, rate limiting, batch delivery
  • Integration Marketplace: Community-contributed templates and hooks
  • MCP Integration: Model Context Protocol support for AI workflows

🤝 Contributing

Help expand Gira's extensibility: - Share webhook templates and hook scripts - Contribute documentation improvements - Suggest new integration patterns - Build templates for popular services

Ready to extend Gira? Start with: - HTTP Webhooks for external service integration - Local Hooks for project-specific automation