Convert JIRA to YML

Why Convert JIRA to YML?

Converting JIRA markup to YML transforms Atlassian project documentation into structured YAML data files using the popular .yml extension. Many DevOps tools and CI/CD platforms specifically use the .yml extension by convention, including Docker Compose (docker-compose.yml), GitHub Actions, and GitLab CI configurations.

This conversion is particularly useful for teams that document their infrastructure and deployment configurations in Jira and need to generate the actual configuration files. By converting Jira specifications to YML, you bridge the gap between human-readable documentation and machine-readable configuration, reducing manual transcription errors.

The YML output preserves the hierarchical structure of Jira content, mapping headings to YAML sections, tables to arrays of mappings, and lists to YAML sequences. Comments extracted from Jira descriptions provide context alongside the structured data, making the generated YML files both functional and well-documented.

Key Benefits of Converting JIRA to YML:

• Tool Convention: Many tools expect the .yml extension specifically
• CI/CD Ready: Direct use in GitHub Actions, GitLab CI, and Jenkins
• Docker Compose: Generate docker-compose.yml from Jira specs
• Human Readable: Clean format that is easy to review and edit
• Comment Support: Preserve documentation as inline YAML comments
• Structured Data: Map Jira tables and lists to YAML data structures
• Cross-Platform: YML files work on all operating systems and tools

Practical Examples

Example 1: Docker Compose Spec to YML

Input JIRA file (docker.jira):

h2. Docker Compose Configuration

h3. Web Service
* Image: myapp:latest
* Port: 8080:80
* Depends On: database, cache

h3. Database Service
* Image: postgres:15
* Port: 5432:5432

h3. Environment Variables
||Service||Variable||Value||
|web|DATABASE_URL|postgres://db:5432/app|
|web|REDIS_URL|redis://cache:6379|
|database|POSTGRES_DB|app|
|database|POSTGRES_PASSWORD|secret|

Output YML file (docker.yml):

# Docker Compose Configuration
# Converted from JIRA markup

web:
  image: "myapp:latest"
  port: "8080:80"
  depends_on:
    - database
    - cache

database:
  image: "postgres:15"
  port: "5432:5432"

environment:
  - service: web
    variable: DATABASE_URL
    value: "postgres://db:5432/app"
  - service: web
    variable: REDIS_URL
    value: "redis://cache:6379"
  - service: database
    variable: POSTGRES_DB
    value: app
  - service: database
    variable: POSTGRES_PASSWORD
    value: secret

Example 2: CI Pipeline Config to YML

Input JIRA file (ci.jira):

h2. GitHub Actions Workflow

*Name:* Build and Deploy
*Trigger:* Push to main branch

h3. Build Job
# Checkout code
# Setup Node.js 20
# Install dependencies
# Run tests
# Build application

h3. Deploy Job
# Download build artifact
# Deploy to production server
# Run health check
# Send notification

Output YML file (ci.yml):

# GitHub Actions Workflow
# Converted from JIRA markup

name: Build and Deploy
trigger: Push to main branch

jobs:
  build:
    steps:
      - Checkout code
      - Setup Node.js 20
      - Install dependencies
      - Run tests
      - Build application

  deploy:
    steps:
      - Download build artifact
      - Deploy to production server
      - Run health check
      - Send notification

Example 3: Application Config to YML

Input JIRA file (config.jira):

h1. Application Configuration

h2. Server Settings
* Host: 0.0.0.0
* Port: 8080
* Workers: 4
* Debug: No

h2. Logging
||Level||Module||Output||
|INFO|app|stdout|
|ERROR|app|file|
|DEBUG|database|file|

h2. Security
* JWT Secret: use-environment-variable
* Token Expiry: 3600
* CORS Origins: https://app.example.com
* Rate Limit: 100 requests per minute

Output YML file (config.yml):

# Application Configuration
# Converted from JIRA markup

server:
  host: "0.0.0.0"
  port: 8080
  workers: 4
  debug: false

logging:
  - level: INFO
    module: app
    output: stdout
  - level: ERROR
    module: app
    output: file
  - level: DEBUG
    module: database
    output: file

security:
  jwt_secret: use-environment-variable
  token_expiry: 3600
  cors_origins: "https://app.example.com"
  rate_limit: "100 requests per minute"

Frequently Asked Questions (FAQ)

Q: What is the difference between YML and YAML?

A: There is no format difference. YML (.yml) and YAML (.yaml) are the same format with different file extensions. The .yaml extension is officially recommended, but .yml is widely used by convention in tools like Docker Compose, GitHub Actions, and Spring Boot.

Q: How is Jira content mapped to YML structure?

A: Jira headings become YML section keys or comments, tables become arrays of mappings, and lists become YML sequences. Key-value patterns in text are extracted as YML key-value pairs with proper indentation.

Q: Can I use the output directly in Docker Compose?

A: The output is valid YAML, but Docker Compose requires a specific schema (version, services, volumes). You can use the converter to generate initial content and then restructure it to match Docker Compose's expected format.

Q: How are Jira tables converted to YML?

A: Jira tables with headers become YML arrays of mappings, where each row is a mapping with header column names as keys. This produces clean, structured YML that preserves the tabular data in a readable format.

Q: Are data types automatically detected?

A: Yes, the converter detects common data types. Numbers become YML integers or floats, boolean values (Yes/No, True/False) become YML booleans, and text becomes quoted strings. You can adjust types after conversion.

Q: Can I use this for GitHub Actions workflows?

A: The output is valid YML that can serve as a starting point for GitHub Actions workflows. You will need to adjust the structure to match the Actions schema (on, jobs, steps, uses) for it to work as a workflow file.

Q: How are Jira code blocks handled in YML?

A: Code block content is stored as multi-line YML strings using the literal block style (|). This preserves line breaks and indentation from the original code content in the Jira markup.

Q: Why use YML instead of YAML extension?

A: Many popular tools and frameworks use .yml by convention: docker-compose.yml, .gitlab-ci.yml, .travis.yml, and application.yml (Spring Boot). Using .yml ensures compatibility with these tools' expected file naming patterns.