# onee-only/ff-merge architecture

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

- Interactive diagram: https://gitdiagram.com/onee-only/ff-merge
- Repository: https://github.com/onee-only/ff-merge

## Overview

##### Project type and purpose
- Type: A GitHub Action packaged as a Dockerized Go application.
- Purpose: Listens for pull_request and issue_comment events on GitHub, validates fast-forward merge conditions, then issues a `git merge --ff-only` (and optional comment) via the GitHub API.

##### File structure
- Top-level action files
– action.yml: action metadata, inputs, outputs
– Dockerfile: build image spec
– main.go: entrypoint and orchestration
- Internal packages
– internal/fastforward: core merge logic
– internal/github: GitHub API client, permission checks, comment logic
– internal/types: shared data structures (e.g., event payload wrappers)
- CI/CD
– .github/workflows/build-push-release.yml: build & publish container
- Config
– go.mod/go.sum: dependency management

##### Extract architecture hints from README
- Supported Events (pull_request, issue_comment)
- Inputs (merge flag, comment policy, allowed-roles, GITHUB_TOKEN)
- Workflow triggers & examples illustrating how the action is invoked

##### Main components & interactions
a. Event Source: GitHub
– pull_request event
– issue_comment event
b. Runner Environment: GitHub Actions hosted runner
– Pulls container image
– Supplies event payload and inputs as environment vars
c. ff-merge Container (Go application)
1. main.go orchestrator
2. internal/types: parse incoming JSON into typed structs
3. internal/github:
- Authenticate to GitHub using GITHUB_TOKEN
- Fetch PR details & actor permissions
- Decide if fast-forward is allowed
- If allowed & merge input=true → merge PR
- If comment policy requires → post comment
4. internal/fastforward:
- Validate head/tip match
- Construct merge commit if applicable
d. External Service: GitHub API endpoints
– GET pull request info
– POST merge command
– POST comments
e. Outputs: Merge result status, optional comment

##### Architectural patterns & design principles
- Modular layering
– Separation of concerns: orchestration (main), domain logic (fastforward), API client (github), data types (types)
- Single‐container, event‐driven function
- Immutable inputs → pure functions for decision logic
- Clear boundary: all side‐effects (API calls) in internal/github

## Diagram (Mermaid)

```mermaid
graph TB
    %% External GitHub Events
    subgraph "GitHub Events" 
        direction TB
        PR["pull_request event"]:::api
        IC["issue_comment event"]:::api
    end

    %% Runner Environment
    subgraph "Runner (GitHub Actions hosted)" 
        direction TB
        Runner["Checkout & Setup\nEnvironment Vars\n(event payload, inputs)"]:::runner
        click Runner "https://github.com/onee-only/ff-merge/blob/main/.github/workflows/build-push-release.yml"
    end

    %% Container
    subgraph "ff-merge Container\n(Dockerized Go Application)" 
        direction TB
        DockerfileNode["Dockerfile"]:::container
        click DockerfileNode "https://github.com/onee-only/ff-merge/tree/main/Dockerfile"
        ActionYML["action.yml\n(inputs/outputs)"]:::container
        click ActionYML "https://github.com/onee-only/ff-merge/blob/main/action.yml"
        main["main.go\n(entrypoint & orchestration)"]:::container
        click main "https://github.com/onee-only/ff-merge/blob/main/main.go"

        subgraph "internal/types" 
            direction TB
            Types["types.go\n(payload wrappers)"]:::types
            click Types "https://github.com/onee-only/ff-merge/blob/main/internal/types/types.go"
        end

        subgraph "internal/github\n(API client & side-effects)" 
            direction TB
            PRInfo["pr_info.go\n(GET PR details & merge)"]:::github
            click PRInfo "https://github.com/onee-only/ff-merge/blob/main/internal/github/pr_info.go"
            Permission["permission.go\n(check permissions)"]:::github
            click Permission "https://github.com/onee-only/ff-merge/blob/main/internal/github/permission.go"
            Comment["comment.go\n(post comments)"]:::github
            click Comment "https://github.com/onee-only/ff-merge/blob/main/internal/github/comment.go"
        end

        subgraph "internal/fastforward\n(core merge logic)" 
            direction TB
            FF["fastforward.go\n(validate & construct merge)"]:::logic
            click FF "https://github.com/onee-only/ff-merge/blob/main/internal/fastforward/fastforward.go"
        end
    end

    %% External GitHub API
    subgraph "GitHub API Endpoints" 
        direction TB
        GETPR["GET /repos/{owner}/{repo}/pulls"]:::api
        POSTMerge["POST /repos/{owner}/{repo}/pulls/{pull_number}/merge"]:::api
        POSTComment["POST /repos/{owner}/{repo}/issues/{issue_number}/comments"]:::api
    end

    %% CI/CD Workflow file and deps
    CICD[".github/workflows/build-push-release.yml"]:::ci
    click CICD "https://github.com/onee-only/ff-merge/blob/main/.github/workflows/build-push-release.yml"
    GoMod["go.mod / go.sum"]:::ci
    click GoMod "https://github.com/onee-only/ff-merge/blob/main/go.mod"
    click GoMod "https://github.com/onee-only/ff-merge/blob/main/go.sum"

    %% Connections
    PR -->|event payload| Runner
    IC -->|event payload| Runner
    Runner -->|runs container| DockerfileNode
    Runner -->|provides inputs| ActionYML
    Runner -->|invokes| main

    main -->|parse JSON| Types
    main -->|authenticate| PRInfo
    main -->|call permission checks| Permission
    main -->|evaluate merge conditions| FF
    FF -->|decision result| main
    main -->|invoke merge if allowed| PRInfo
    main -->|invoke comment if policy| Comment

    PRInfo -.->|GET pull request info| GETPR
    PRInfo -.->|POST merge command| POSTMerge
    Comment -.->|POST comment| POSTComment

    %% Class Definitions
    classDef runner fill:#CFE2F3,stroke:#000,stroke-width:1px;
    classDef container fill:#D9EAD3,stroke:#000,stroke-width:1px;
    classDef github fill:#EAD1DC,stroke:#000,stroke-width:1px;
    classDef logic fill:#F4CCCC,stroke:#000,stroke-width:1px;
    classDef types fill:#FFF2CC,stroke:#000,stroke-width:1px;
    classDef api fill:#F9CB9C,stroke:#000,stroke-width:1px;
    classDef ci fill:#D0E0E3,stroke:#000,stroke-width:1px;
```
