Skip to content

Custom Fields

Custom fields allow you to extend Gira with project-specific data fields for tickets and epics. This feature enables teams to track additional information beyond Gira's standard fields without modifying the core codebase.

Overview

Custom fields are defined in your project's .gira/config.json file and support multiple data types: - String: Text values with optional regex validation - Integer: Numeric values with optional min/max constraints - Boolean: True/false values - Date: ISO format dates (YYYY-MM-DD) - Enum: Predefined list of options

Configuration

Custom fields are configured in the custom_fields section of your project configuration:

{
  "custom_fields": {
    "fields": [
      {
        "name": "customer_impact",
        "display_name": "Customer Impact Score",
        "type": "integer",
        "applies_to": "ticket",
        "required": false,
        "min_value": 1,
        "max_value": 10,
        "description": "Impact score from 1 (low) to 10 (critical)"
      },
      {
        "name": "environment",
        "display_name": "Environment",
        "type": "enum",
        "applies_to": "ticket",
        "required": true,
        "options": ["development", "staging", "production"],
        "default_value": "development",
        "description": "Environment where the issue occurs"
      }
    ]
  }
}

Field Definition Properties

Property Type Required Description
name string Yes Field identifier (lowercase, alphanumeric with underscores)
display_name string Yes Human-readable name for display
type string Yes Field type: string, integer, boolean, date, enum
applies_to string No Entity type: ticket, epic, or all (default: all)
required boolean No Whether the field is mandatory (default: false)
default_value varies No Default value if not provided
description string No Help text for the field

Type-Specific Properties

String Fields

  • validation_pattern: Regex pattern for validation

Integer Fields

  • min_value: Minimum allowed value
  • max_value: Maximum allowed value

Enum Fields

  • options: Array of allowed values (required)

Usage

Creating Tickets with Custom Fields

Use the --cf option to set custom field values:

# Single custom field
gira ticket create "Fix login bug" --cf customer_impact=8

# Multiple custom fields
gira ticket create "Production issue" \
  --cf customer_impact=9 \
  --cf environment=production \
  --cf regression=true

# With other standard options
gira ticket create "Security patch" \
  --priority high \
  --type bug \
  --cf customer_impact=10 \
  --cf due_date=2025-02-15

Updating Custom Fields

Update existing custom fields or add new ones:

# Update custom field value
gira ticket update GIRA-123 --cf environment=staging

# Add multiple custom fields
gira ticket update GIRA-123 \
  --cf due_date=2025-03-01 \
  --cf external_id=EXT-4567

# Remove a custom field
gira ticket update GIRA-123 --remove-cf regression

Bulk Operations

Custom fields are supported in bulk creation via JSON:

[
  {
    "title": "First ticket",
    "type": "bug",
    "custom_fields": {
      "customer_impact": 7,
      "environment": "production"
    }
  },
  {
    "title": "Second ticket",
    "type": "feature",
    "custom_fields": {
      "customer_impact": 3,
      "environment": "development"
    }
  }
]

cat tickets.json | gira ticket create --stdin

Field Types

String Fields

Text fields with optional pattern validation:

{
  "name": "external_id",
  "display_name": "External Reference ID",
  "type": "string",
  "validation_pattern": "^EXT-\\d{4,}$",
  "description": "External system reference (format: EXT-####)"
}

Integer Fields

Numeric fields with optional range constraints:

{
  "name": "priority_score",
  "display_name": "Priority Score",
  "type": "integer",
  "min_value": 1,
  "max_value": 100,
  "default_value": 50
}

Boolean Fields

True/false fields:

{
  "name": "is_regression",
  "display_name": "Is Regression?",
  "type": "boolean",
  "default_value": false
}

Command line values: true, false, yes, no, 1, 0, on, off

Date Fields

ISO format date fields:

{
  "name": "target_date",
  "display_name": "Target Date",
  "type": "date",
  "description": "Expected completion date"
}

Format: YYYY-MM-DD (e.g., 2025-12-31)

Enum Fields

Predefined list of options:

{
  "name": "severity",
  "display_name": "Severity",
  "type": "enum",
  "options": ["low", "medium", "high", "critical"],
  "default_value": "medium",
  "required": true
}

Best Practices

  1. Naming Convention: Use lowercase with underscores for field names (e.g., customer_impact, not CustomerImpact)

  2. Required Fields: Use sparingly - required fields must be provided for every ticket/epic creation

  3. Default Values: Provide sensible defaults for commonly used fields

  4. Validation: Use validation patterns and constraints to ensure data quality

  5. Documentation: Always include descriptions to help users understand field purpose

Example Configuration

Here's a comprehensive example for a software project:

{
  "custom_fields": {
    "fields": [
      {
        "name": "customer_impact",
        "display_name": "Customer Impact Score",
        "type": "integer",
        "applies_to": "ticket",
        "min_value": 1,
        "max_value": 10,
        "description": "Customer impact rating (1=minimal, 10=critical)"
      },
      {
        "name": "environment",
        "display_name": "Environment",
        "type": "enum",
        "applies_to": "ticket",
        "options": ["dev", "test", "staging", "prod"],
        "default_value": "dev",
        "required": true,
        "description": "Affected environment"
      },
      {
        "name": "regression",
        "display_name": "Regression Bug",
        "type": "boolean",
        "applies_to": "ticket",
        "default_value": false,
        "description": "Was this working before?"
      },
      {
        "name": "sla_date",
        "display_name": "SLA Date",
        "type": "date",
        "applies_to": "ticket",
        "description": "Service level agreement deadline"
      },
      {
        "name": "jira_id",
        "display_name": "JIRA Reference",
        "type": "string",
        "applies_to": "all",
        "validation_pattern": "^[A-Z]{2,}-\\d+$",
        "description": "Legacy JIRA ticket reference"
      },
      {
        "name": "business_value",
        "display_name": "Business Value",
        "type": "enum",
        "applies_to": "epic",
        "options": ["low", "medium", "high", "critical"],
        "required": true,
        "description": "Strategic business value"
      }
    ]
  }
}

Storage

Custom field values are stored in the custom_fields object within ticket and epic JSON files:

{
  "id": "GIRA-123",
  "title": "Production login issue",
  "type": "bug",
  "priority": "high",
  "custom_fields": {
    "customer_impact": 9,
    "environment": "prod",
    "regression": true,
    "sla_date": "2025-02-01",
    "jira_id": "PROJ-4567"
  }
}

Limitations

  • Field names must be unique within a project
  • Field types cannot be changed after data has been created
  • Maximum of 50 custom fields per project (configurable)
  • Field names cannot conflict with built-in field names

Migration

When modifying custom field definitions:

  1. Adding Fields: New fields are immediately available for use
  2. Removing Fields: Existing data is preserved but field is no longer validated
  3. Changing Types: Not supported - create a new field instead
  4. Renaming: Create new field and migrate data manually

See Also