# mathieudutour/github-tag-action architecture

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

- Interactive diagram: https://gitdiagram.com/mathieudutour/github-tag-action
- Repository: https://github.com/mathieudutour/github-tag-action

## Overview

##### Project Type & Purpose
- Type: Open-source GitHub Action (Node.js / TypeScript)
- Purpose: On merge to a release branch, compute next SemVer version, tag the commit, generate a changelog, and expose outputs for downstream steps (e.g., GitHub Release).

##### File Structure
- Top‐level:
- action.yml – defines inputs/outputs, entrypoint
- src/ – core TypeScript modules
- tests/ – unit tests for logic
- docs/ – publishing instructions
- src modules:
- main.ts – orchestrates the action’s lifecycle
- action.ts – reads inputs, calls core logic
- github.ts – wraps GitHub REST API calls (fetch tags, create tag)
- ts.ts – Semantic-versioning logic
- utils.ts & defaults.ts – helper functions and default settings

##### Extract Key Components
- GitHub Actions Runner (hosted Ubuntu, Node.js runtime)
- Action Entrypoint (compiled JavaScript from main.ts)
- Core Logic Modules:
- Input Parser (action.ts)
- Version Calculator (ts.ts + defaults.ts)
- GitHub API Client (github.ts)
- Utilities (utils.ts)
- External Systems: GitHub REST API
- Outputs: New tag name, previous tag, changelog, etc.

##### Relationships & Data Flows
- Runner → Entrypoint (main.js invoked by action.yml)
- Entrypoint calls Input Parser → passes parameters to Version Calculator
- Version Calculator consults GitHub API Client to fetch existing tags
- Calculator computes next version & changelog via semantic rules
- GitHub API Client creates a new tag reference in the repo
- Action returns outputs to the workflow

##### Architectural Patterns
- Modular design: separation of concerns (I/O, logic, HTTP calls)
- Single‐process, event-driven flow
- Use of conventional semantic-release conventions for versioning

- Component boundaries (modules vs. external)
- Data stores: Git tags on GitHub

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment
    Runner["GitHub Actions Runner"]:::env

    %% Internal Modules
    subgraph "Internal Modules"
        Entrypoint["Action Entrypoint\n(main.js)"]:::internal
        Parser["Input Parser\n(action.ts)"]:::internal
        Calculator["Version Calculator\n(ts.ts & defaults.ts)"]:::internal
        GitClient["GitHub API Client\n(github.ts)"]:::internal
        Utils["Utilities\n(utils.ts)"]:::internal
        Outputs["Outputs\n(new_tag, changelog, etc.)"]:::internal
    end

    %% External Systems
    API["GitHub REST API"]:::external

    %% Documentation & Testing & Workflow
    Docs["Documentation\n(how-to-publish-new-version.md)"]:::docs
    Workflow["Workflow Example\n(test.yml)"]:::docs
    Tests["Unit Tests"]:::tests

    %% Data Flows
    Runner -->|"invokes"| Entrypoint
    Entrypoint -->|"reads inputs"| Parser
    Parser -->|"parsed inputs"| Calculator
    Calculator -->|"fetch tags"| GitClient
    GitClient -->|"tag list"| Calculator
    Calculator -->|"compute version & changelog"| Outputs
    Calculator -->|"create tag request"| GitClient
    GitClient -->|"HTTP call"| API
    API -->|"response"| GitClient
    GitClient -->|"acknowledgment"| Calculator
    Entrypoint -->|"uses helpers"| Utils
    Parser -->|"uses helpers"| Utils
    Calculator -->|"uses helpers"| Utils

    %% Related Artifacts
    Parser --> Docs
    Entrypoint --> Workflow
    Parser --> Tests
    Calculator --> Tests
    GitClient --> Tests
    Utils --> Tests

    %% Click Events
    click Runner "https://github.com/mathieudutour/github-tag-action/blob/master/.github/workflows/test.yml"
    click Entrypoint "https://github.com/mathieudutour/github-tag-action/blob/master/action.yml"
    click Entrypoint "https://github.com/mathieudutour/github-tag-action/blob/master/src/main.ts"
    click Parser "https://github.com/mathieudutour/github-tag-action/blob/master/src/action.ts"
    click Calculator "https://github.com/mathieudutour/github-tag-action/blob/master/src/ts.ts"
    click Calculator "https://github.com/mathieudutour/github-tag-action/blob/master/src/defaults.ts"
    click GitClient "https://github.com/mathieudutour/github-tag-action/blob/master/src/github.ts"
    click Utils "https://github.com/mathieudutour/github-tag-action/blob/master/src/utils.ts"
    click Tests "https://github.com/mathieudutour/github-tag-action/blob/master/tests/action.test.ts"
    click Tests "https://github.com/mathieudutour/github-tag-action/blob/master/tests/github.test.ts"
    click Tests "https://github.com/mathieudutour/github-tag-action/blob/master/tests/helper.test.ts"
    click Tests "https://github.com/mathieudutour/github-tag-action/blob/master/tests/utils.test.ts"
    click Docs "https://github.com/mathieudutour/github-tag-action/blob/master/docs/how-to-publish-new-version.md"

    %% Styles
    classDef env fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef internal fill:#b9f6ca,stroke:#2e7d32,stroke-width:1px;
    classDef external fill:#81d4fa,stroke:#0277bd,stroke-width:1px;
    classDef docs fill:#fff59d,stroke:#f9a825,stroke-width:1px;
    classDef tests fill:#ffccbc,stroke:#bf360c,stroke-width:1px;
```
