How github/ghas-jira-integration works
Project Type and Purpose
• This is an open-source integration tool (written in Python) that synchronizes GitHub Code Scanning alerts with Jira issues.
• It can be invoked as:
a) A GitHub Action (one-way sync: GitHub → Jira)
b) A CLI utility (poll-based sync, one- or two-way)
c) A Flask-based server (event-driven, two-way via webhooks)
Main Components
A. Core Sync Library
• ghlib.py – GitHub REST/Webhook client
• jiralib.py – Jira REST client
• util.py – shared helpers
• sync.py – orchestrates alert ↔ issue mapping operations
B. Adapters
1. GitHub Action Adapter
• action.yml – Action metadata
• Dockerfile + entrypoint.sh – container & startup script
2. CLI Adapter
• cli.py – “gh2jira” CLI entrypoint
3. Server Adapter
• server.py – Flask app exposing /github & /jira endpoints
C. External Systems
• GitHub Code Scanning API
• GitHub Webhooks
• Jira Server REST API
• Jira Webhooks
D. Optional State Storage
• Local JSON file (state-file) or
• Dedicated Jira issue for state
Relationships and Data Flows
• One-way Polling (CLI or Action):
[CLI/Action Adapter] ––REST–→ [GitHub API] ←fetch alerts
[CLI/Action Adapter] ––REST–→ [Jira API] ←create/update/delete issues
• Two-way Polling (CLI with --direction both): same as above but bidirectional
• Two-way Event-Driven (Server):
a) GitHub → Webhook → Flask server.py → sync logic → Jira API
b) Jira → Webhook → Flask server.py → sync logic → GitHub API
• Optional state persistence calls down to JSON or Jira issue
Architectural Patterns & Principles
• Adapter Pattern: separate transport layers (Action, CLI, Server) from business logic (sync.py)
• Layered Design:
• Presentation/Transport layer (Flask endpoints, CLI args, GitHub Action runner)
• Application layer (sync orchestration)
• Integration layer (ghlib, jiralib for REST calls)
• Event-Driven (via webhooks) vs. Polling (via REST) modes
• Single Responsibility: each Python module has a clear focus
Technologies & Frameworks
• Python 3.5+
• Flask (lightweight HTTP server)
• GitHub Action (Docker-based)
• Pipenv (dependency management)
• GitHub & Jira REST APIs & Webhooks