Sync2Jira

Overview

Sync2Jira is a service that listens to activity on upstream GitHub repositories via fedmsg and automatically syncs issues and pull requests to downstream JIRA instances. It provides real-time synchronization capabilities, ensuring that your JIRA project stays up-to-date with upstream development activity.

Key Features

• Real-time Synchronization: Listens to fedmsg events from GitHub for immediate updates
• Sync: Supports both issues and pull requests
• Flexible Configuration: Map multiple GitHub repositories to different JIRA projects
• Custom Field Support: Sync labels, assignees, milestones and custom fields such as priority and story points
• Batch Initialization: Initial sync of all existing issues and PRs
• Manual Sync Interface: Web UI for on-demand repository synchronization
• Comprehensive Filtering: Filter by labels, milestones, and other criteria
• Email Notifications: Alert administrators on sync failures

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   GitHub Repo   │───▶│   Fedmsg/       │───▶│   Sync2Jira     │───▶│   JIRA Project  │
│   (Issues/PRs)  │    │   Fedora        │    │   (Service)     │    │   (Issues)      │
│                 │    │   Messaging     │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘

Core Components

• Sync2Jira: Main synchronization service that listens for GitHub events and creates/updates JIRA issues
• Sync Page: UI for manually triggering synchronization of specific repositories when needed

Installation

Prerequisites

• Python 3.12+
• JIRA API access using one of:
  • PAT (Personal Access Token / API token): email + API token (e.g. Jira Cloud)
  • OAuth 2.0 (2LO): Atlassian service account client ID and secret
• GitHub API token
• Fedora messaging environment (for production)

From Source

# Clone the repository
git clone https://github.com/release-engineering/Sync2Jira.git
cd Sync2Jira

# Install dependencies
pip install -r requirements.txt

# Install package
pip install .

# Run the service
sync2jira

# With initialization (sync all existing issues)
INITIALIZE=1 sync2jira

# Testing mode (dry run)
# Set testing: True in config file
sync2jira

Note: Container images are also available as an alternative to native installation. See the Usage section for container deployment instructions.

Configuration

Create a configuration file in the fedmsg.d/ directory. Here's a basic example:

# fedmsg.d/sync2jira.py
config = {
    'sync2jira': {
        # GitHub API token
        'github_token': 'your_github_token',
        
        # JIRA configuration
        'default_jira_instance': 'primary',
        'jira': {
            'primary': {
                'options': {
                    'server': 'https://your-jira.example.com',
                    'verify': True,
                },
                'auth_method': 'pat',    # Use 'pat' (default) or 'oauth2'
                # For PAT: email and API token (e.g. Jira Cloud)
                'basic_auth': ('your-email@example.com', 'YOUR_JIRA_API_TOKEN'),
                # For OAuth 2.0: set auth_method to 'oauth2' and replace 'basic_auth' with:
                # 'oauth2': {
                #     'client_id': 'YOUR_CLIENT_ID',
                #     'client_secret': 'YOUR_CLIENT_SECRET',
                # },
            },
        },
        
        # Repository mappings
        'map': {
            'github': {
                'username/repository': {
                    'project': 'JIRA_PROJECT_KEY',
                    'component': 'component-name',
                    'sync': ['issue', 'pullrequest'],
                    'issue_updates': [
                        'comments',
                        'title',
                        'description',
                        {'tags': {'overwrite': True}},
                        {'assignee': {'overwrite': False}},
                        'url'
                    ],
                },
            },
        },
        
        # Optional settings
        'testing': False,  # Set to True for dry-run mode
        'initialize': False,  # Set to True to sync all existing issues
        'admins': ['admin_username'],  # Email notifications
    }
}

Configuration Options

Option	Description	Default
github_token	GitHub API token for authentication	Required
jira	JIRA instance configs (per-instance: PAT via basic_auth or OAuth 2.0 via oauth2)	Required
map	Repository-to-project mappings	Required
testing	Enable dry-run mode (no actual changes)	False
initialize	Sync all existing issues on startup	False
filters	Filter issues by labels, milestones, etc.	{}
admins	List of admin users for notifications	[]

JIRA authentication: Each JIRA instance can use PAT (auth_method: 'pat', with basic_auth: email + API token) or OAuth 2.0 (auth_method: 'oauth2', with oauth2: client_id and client_secret from an Atlassian service account). See the Configuration Reference for details.

Usage

Sync2Jira Service

The main synchronization service that listens for GitHub events and creates/updates JIRA issues.

Native Installation

# Run the service
sync2jira

# With initialization (sync all existing issues)
INITIALIZE=1 sync2jira

# Testing mode (dry run)
# Set testing: True in config file
sync2jira

Container Deployment

# Basic usage - run the sync service
docker run -v /path/to/your/config:/etc/fedmsg.d/ \
           -e GITHUB_TOKEN=your_token \
           -e JIRA_TOKEN=your_jira_token \
           quay.io/redhat-services-prod/sync2jira/sync2jira:latest

# With initialization (sync all existing issues)
docker run -v /path/to/your/config:/etc/fedmsg.d/ \
           -e GITHUB_TOKEN=your_token \
           -e JIRA_TOKEN=your_jira_token \
           -e INITIALIZE=1 \
           quay.io/redhat-services-prod/sync2jira/sync2jira:latest

Note: The -v /path/to/your/config:/etc/fedmsg.d/ option mounts your local configuration directory inside the container, allowing the containerized application to use your host system's configuration files.

Sync Page UI

A web interface for manually triggering synchronization of specific repositories when needed.

Native Installation

# Navigate to the sync-page directory
cd sync-page

# Run the Flask application
python event-handler.py

Container Deployment

# Run the web interface for manual synchronization
docker run -v /path/to/your/config:/etc/fedmsg.d/ \
           -p 5000:5000 \
           -e GITHUB_TOKEN=your_token \
           -e JIRA_TOKEN=your_jira_token \
           quay.io/redhat-aqe/sync2jira:sync-page

Access the interface:

• Local development: http://localhost:5000 (or whatever port Flask shows)
• Production: Configure according to your deployment environment

Environment Variables

The following environment variables can be used to configure both tools:

Common Variables (used by both sync2jira and sync-page):

• GITHUB_TOKEN: GitHub API token (can override config)
• JIRA_TOKEN: JIRA API token (can override config)

Sync2Jira Service Only:

• INITIALIZE: Set to 1 to perform initial sync of all issues
• FEDORA_MESSAGING_QUEUE: Custom message queue name

Documentation

Comprehensive documentation is available at sync2jira.readthedocs.io:

• Quick Start Guide
• Configuration Reference
• Sync Page Usage

License

This project is licensed under the GNU Lesser General Public License v2.1 or later (LGPLv2+). See the LICENSE file for details.

Support

• Documentation: https://sync2jira.readthedocs.io
• Issues: GitHub Issues

Maintainers

• Ralph Bean (@ralphbean)
• Red Hat Release Engineering Team

---

Sync2Jira is part of the Red Hat Release Engineering toolchain and is used in production to sync thousands of issues across multiple projects.