# sethvargo/go-githubactions architecture

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

- Interactive diagram: https://gitdiagram.com/sethvargo/go-githubactions
- Repository: https://github.com/sethvargo/go-githubactions

## Overview

##### Project Type and Purpose
- This is an open-source Go SDK for authoring GitHub Actions (a library/tool rather than a full-stack app). Its primary role is to provide Go functions that emit the special commands and environment manipulations expected by the GitHub Actions runner.

##### File Structure Analysis
- Top-level code files (actions.go, command.go, options.go, eof_*.go) implement the core functionality: wrapping GH Actions commands, parsing inputs, formatting output, handling line endings, etc.
- Test files (actions_test.go, command_test.go, options_test.go, actions_doc_test.go) verify each module.
- .github/workflows/unit.yml runs your unit tests on each push.
- No frontend, no database—this is purely a library + CI + packaging tool.

##### README Insights
- Usage examples show how client code imports the library and invokes functions to read inputs or log errors.
- Publishing section demonstrates two packaging flows:
a. Composite Actions (YAML only)
b. Go binary → Docker image → Docker Hub → runner pulls minimal scratch container
- Multi-stage Docker build example highlights build stage vs scratch stage for tiny container.

a. Main Components
- Client Action Code (user’s Go code)
- go-githubactions Library (modules for commands, options, I/O)
- GitHub Actions Runner (the execution environment)
- Docker Build Pipeline (multi-stage build: builder image → scratch image)
- Docker Registry (Docker Hub or GH Container Registry)
- CI Pipeline (GitHub Actions workflows for tests)

b. Relationships & Data Flow
1. Developer writes Client Action Code that imports go-githubactions.
2. Code calls library APIs (GetInput, SetOutput, Group, Debugf, Fatalf, etc.).
3. Library emits formatted commands to STDOUT or writes to `$GITHUB_OUTPUT`, `$GITHUB_ENV`.
4. GitHub Actions Runner reads these commands at runtime to control workflow steps.
5. For packaging: Multi-stage Docker Build process compiles the Go binary in a builder stage, strips and compresses it, then copies into a minimal scratch image.
6. Resulting container is pushed to a Docker Registry.
7. Workflow steps in end-user repos use `uses: docker://username/repo:tag` to pull and run the container.

c. Architectural Patterns & Principles
- Single Responsibility: each Go file handles one concern (commands, options, EOF).
- Dependency-free core: no external Go dependencies means simpler static builds.
- CI as code: unit tests in YAML automatically verify every commit.
- Multi-stage build for minimal final artifact (security and size).

d. Key Technologies & Frameworks
- Language & Tooling: Go modules, `go build`, `go test`
- CI: GitHub Actions Workflows (`.github/workflows/unit.yml`)
- Containerization: Docker multi-stage builds, UPX, scratch images
- Registry: Docker Hub or GitHub Container Registry

##### Detail & Coverage
- You capture each module (.go file) as part of the Library component or annotate major submodules.
- Unit test suite and workflow file as part of the CI Pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Code
    ClientCode["Client Action Code"]:::library

    %% Core Library Subgraph
    subgraph "go-githubactions Core Library"
        direction TB
        Commands["Commands Module"]:::library
        Options["Options Module"]:::library
        ActionsAPI["Actions API"]:::library
        EOFHandling["EOF Handling"]:::library
    end

    %% CI Pipeline Subgraph
    subgraph "CI Pipeline"
        direction TB
        UnitTests["Unit Tests Suite"]:::ci
        CIWorkflow["CI Workflow (.github/workflows/unit.yml)"]:::ci
    end

    %% Build & Packaging Subgraph
    subgraph "Build & Packaging"
        direction TB
        MakefileNode["Makefile"]:::build
        BuilderImage["Docker Builder Stage"]:::build
        ScratchImage["Docker Scratch Image"]:::build
    end

    %% External Services
    Runner["GitHub Actions Runner"]:::external
    Registry["Docker Registry"]:::external
    RepoDocs["Repository Metadata"]:::external
    GoMod["Go Module Config"]:::external

    %% Relationships
    ClientCode -->|"imports APIs"| ActionsAPI
    ClientCode -->|calls| Commands
    ClientCode -->|calls| Options
    ClientCode -->|uses| EOFHandling

    Commands -->|"emits commands to STDOUT / $GITHUB_*"| Runner
    Options -->|manages inputs/outputs| Runner
    ActionsAPI -->|invokes grouping/logging| Runner
    EOFHandling -->|handles line endings| Runner

    CIWorkflow -->|runs| UnitTests
    UnitTests -->|validates| Commands
    UnitTests -->|validates| Options
    UnitTests -->|validates| ActionsAPI
    UnitTests -->|validates| EOFHandling

    Commands -->|built by| MakefileNode
    Options -->|built by| MakefileNode
    ActionsAPI -->|built by| MakefileNode
    EOFHandling -->|built by| MakefileNode

    MakefileNode -->|docker build| BuilderImage
    BuilderImage -->|copy binary| ScratchImage
    ScratchImage -->|push| Registry
    Registry -->|pull| Runner

    RepoDocs -->|describes| ClientCode
    GoMod -->|configures| Commands

    %% Click Events
    click Commands "https://github.com/sethvargo/go-githubactions/blob/main/command.go"
    click Options "https://github.com/sethvargo/go-githubactions/blob/main/options.go"
    click ActionsAPI "https://github.com/sethvargo/go-githubactions/blob/main/actions.go"
    click EOFHandling "https://github.com/sethvargo/go-githubactions/blob/main/eof_lf.go"
    click UnitTests "https://github.com/sethvargo/go-githubactions/blob/main/actions_test.go"
    click CIWorkflow "https://github.com/sethvargo/go-githubactions/blob/main/.github/workflows/unit.yml"
    click RepoDocs "https://github.com/sethvargo/go-githubactions/blob/main/README.md"
    click GoMod "https://github.com/sethvargo/go-githubactions/blob/main/go.mod"
    click MakefileNode "https://github.com/sethvargo/go-githubactions/tree/main/Makefile"

    %% Styles
    classDef library fill:#e0ffe0,stroke:#008000,color:#006400
    classDef external fill:#cfe2ff,stroke:#084298,color:#0b5394
    classDef build fill:#ffe0b3,stroke:#b45f06,color:#783f04
    classDef ci fill:#d3d3d3,stroke:#666666,color:#333333
```
