# github/ghas-jira-integration architecture

> Architecture diagram of the GitHub repository github/ghas-jira-integration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/ghas-jira-integration
- Repository: https://github.com/github/ghas-jira-integration

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraphs
    subgraph "Adapters" 
        direction TB
        subgraph "GitHub Action Adapter" 
            direction TB
            A1(["action.yml"]):::adapter
            A2(["entrypoint.sh"]):::adapter
            A3(["Dockerfile"]):::adapter
            A1 --> A2
            A2 --> A3
        end
        subgraph "CLI Adapter" 
            direction TB
            C1(["cli.py"]):::adapter
        end
        subgraph "Server Adapter" 
            direction TB
            S1(["server.py"]):::adapter
        end
    end

    subgraph "Core Sync Library"
        direction TB
        L1(["ghlib.py"]):::core
        L2(["jiralib.py"]):::core
        L3(["util.py"]):::core
        L4(["sync.py"]):::core
    end

    subgraph "External Systems"
        direction TB
        E1(["GitHub Code Scanning API"]):::external
        E2(["GitHub Webhooks"]):::external
        E3(["Jira Server REST API"]):::external
        E4(["Jira Webhooks"]):::external
    end

    subgraph "State Storage (Optional)" 
        direction TB
        ST1(["Local JSON file"]):::storage
        ST2(["Dedicated Jira Issue"]):::storage
    end

    %% Connections Polling (CLI/Action)
    C1 -->|"invokes sync.py\nREST/HTTP"| L4
    A3 -->|"runs entrypoint.sh\nREST/HTTP"| L4
    L4 -->|"REST/HTTP"| E1
    E1 -->|"REST/HTTP"| L4
    L4 -->|"REST/HTTP"| E3

    %% Two-way CLI
    C1 -->|"\u21FD Bidirectional"| E3
    C1 -->|"\u21FD Bidirectional"| E1

    %% Event-driven (Server)
    E2 -->|"Webhook POST + Secret"| S1
    E4 -->|"Webhook POST + Secret"| S1
    S1 -->|"routes to sync.py"| L4
    L4 -->|"REST/HTTP"| E1
    L4 -->|"REST/HTTP"| E3

    %% State persistence
    L4 -->|"persist state"| ST1
    L4 -->|"persist state"| ST2

    %% Click Events
    click L1 "https://github.com/github/ghas-jira-integration/blob/main/ghlib.py"
    click L2 "https://github.com/github/ghas-jira-integration/blob/main/jiralib.py"
    click L3 "https://github.com/github/ghas-jira-integration/blob/main/util.py"
    click L4 "https://github.com/github/ghas-jira-integration/blob/main/sync.py"
    click A1 "https://github.com/github/ghas-jira-integration/blob/main/action.yml"
    click A2 "https://github.com/github/ghas-jira-integration/blob/main/entrypoint.sh"
    click A3 "https://github.com/github/ghas-jira-integration/tree/main/Dockerfile"
    click C1 "https://github.com/github/ghas-jira-integration/blob/main/cli.py"
    click S1 "https://github.com/github/ghas-jira-integration/blob/main/server.py"

    %% Styles
    classDef adapter fill:#D0E8FF,stroke:#024B9A,stroke-width:1px
    classDef core fill:#DFFFE0,stroke:#27632A,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 5 5
    classDef storage fill:#FFF4D6,stroke:#B07B00,stroke-width:1px
```
