# actions/upload-artifact architecture

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

- Interactive diagram: https://gitdiagram.com/actions/upload-artifact
- Repository: https://github.com/actions/upload-artifact

## Overview

##### Project type and purpose
- This is an open-source GitHub Action (Node.js/TypeScript module) whose primary job is to upload workflow artifacts (`upload-artifact`) and to merge previously uploaded artifacts (`merge`). It exposes two sub-actions (defined in `action.yml` at the root and in `merge/action.yml`), compiles from `src/` into `dist/`, and is published to npm and the GitHub Marketplace.

##### File structure
- Top-level:
- action.yml (main action definition)
- merge/action.yml (merge sub-action definition)
- src/
– src/upload/… (upload logic)
– src/merge/… (merge-artifacts logic)
– src/shared/… (common helpers: file discovery, upload-artifact client)
- dist/ (compiled output, parallel to src/)
- __tests__/ (unit tests for search, merge, upload)
- docs/, jest.config.js, package.json, etc.
- The `action.yml` files declare inputs/outputs and point to the compiled entrypoints in `dist/`. Shared modules enforce separation of concerns: input parsing, file-glob searching, artifact-client interactions.

##### README for additional insights
- The README describes features (v4 speed, immutability, compression level, breaking changes) and points to the `@actions/artifact` toolkit. It also references the `merge` sub-action README in `merge/README.md`.

##### Main components and their interactions
1. GitHub Actions Runner (host environment)
2. Action Entry Points
– upload-artifact entrypoint (`dist/upload/index.js`)
– merge entrypoint (`dist/merge/index.js`)
3. Input Helpers (`src/*/input-helper.ts`)
4. File Discovery Module (`src/shared/search.ts`)
5. Artifact Client (`src/shared/upload-artifact.ts` and toolkit `@actions/artifact`)
6. Merge Logic (`src/merge/merge-artifacts.ts`)
7. GitHub REST API / Artifact Storage Service
8. Local filesystem and workflow directory
b. Relationships / data flow:
- Runner reads `action.yml` → spawns Node.js process → calls entrypoint
- Entrypoint loads inputs via Input Helper → invokes File Discovery → returns file list
- For upload: passes file list to Artifact Client → batches/zips files → sends HTTP requests to GitHub REST API → stores artifact → returns outputs (`artifact-id`, `artifact-url`, etc.)
- For merge: Input Helper parses merge parameters → loads existing artifact chunks via Artifact Client → merges them → uploads a new merged artifact back through the same Artifact Client → returns merge outputs
c. Architectural patterns:
- Modular design with clear separation (Input parsing, File I/O, API client, merge logic)
- Shared library code under `src/shared` to enforce DRY across sub-actions
- Compiled distribution artifacts (`dist/`) for deterministic runtime
d. Key technologies / libraries:
- TypeScript → compiled to JavaScript
- `@actions/core` for logging, inputs/outputs
- `@actions/glob` for file pattern matching
- `@actions/artifact` for low-level artifact upload/download
- Jest for unit testing

##### Elements
- Labels: e.g., “Input Helper,” “File Discovery,” “Artifact Client,” “GitHub API,” “Storage Service”
- External services (green) for GitHub API / Storage
- Data stores (yellow) for local filesystem & zipped archives

##### Detailed architectural elements to capture
- Two entrypoints (upload / merge) converging on the shared helper modules
- The lifecycle of an artifact: search → zip → upload → return metadata
- The separate merge workflow: download existing pieces → combine → re-upload
- Configuration & input parsing before any file or network operation
- The boundary between the Action code and the GitHub infrastructure (REST API calls)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% GitHub Runner
    Runner["GitHub Actions Runner"]:::external

    %% Action Definitions
    subgraph "Action Definitions"
        ActionYML["action.yml"]:::module
        MergeYML["merge/action.yml"]:::module
    end

    Runner -->|"reads definitions"| ActionYML
    Runner -->|"reads definitions"| MergeYML

    %% Entry Points
    subgraph "Compiled Entrypoints"
        UploadEntrypoint["dist/upload/index.js"]:::module
        MergeEntrypoint["dist/merge/index.js"]:::module
    end

    ActionYML --> UploadEntrypoint
    MergeYML --> MergeEntrypoint

    %% Shared Modules
    subgraph "Shared Modules"
        FileDiscovery["File Discovery\n(src/shared/search.ts)"]:::module
        ArtifactClient["Artifact Client\n(src/shared/upload-artifact.ts)"]:::module
    end

    %% Upload Action Flow
    subgraph "Upload Action"
        UInputHelper["Input Helper\n(src/upload/input-helper.ts)"]:::module
        UInputs["Input Definitions\n(src/upload/upload-inputs.ts)"]:::module
        UploadLogic["Upload Logic\n(src/upload/upload-artifact.ts)"]:::module
        LocalFS["Local Filesystem"]:::datastore
        GitHubAPI["GitHub REST API"]:::external
        Storage["Artifact Storage Service"]:::external
    end

    UploadEntrypoint --> UInputHelper
    UploadEntrypoint --> UInputs
    UInputHelper --> FileDiscovery
    FileDiscovery --> LocalFS
    FileDiscovery --> UploadLogic
    UploadLogic --> ArtifactClient
    ArtifactClient -->|"HTTP upload"| GitHubAPI
    GitHubAPI --> Storage
    ArtifactClient -->|returns metadata| UploadEntrypoint

    %% Merge Action Flow
    subgraph "Merge Action"
        MInputHelper["Input Helper\n(src/merge/input-helper.ts)"]:::module
        MInputs["Input Definitions\n(src/merge/merge-inputs.ts)"]:::module
        MergeLogic["Merge Logic\n(src/merge/merge-artifacts.ts)"]:::module
        ZippedArtifacts["Existing Artifact Chunks"]:::datastore
        MergedArtifact["Merged Artifact"]:::datastore
    end

    MergeEntrypoint --> MInputHelper
    MergeEntrypoint --> MInputs
    MInputHelper --> ArtifactClient
    ArtifactClient -->|"download chunks"| GitHubAPI
    GitHubAPI --> ZippedArtifacts
    ZippedArtifacts --> MergeLogic
    MergeLogic --> ArtifactClient
    ArtifactClient -->|"upload merged"| GitHubAPI
    GitHubAPI --> MergedArtifact
    ArtifactClient -->|returns merge metadata| MergeEntrypoint

    %% Click Events
    click UploadEntrypoint "https://github.com/actions/upload-artifact/blob/main/dist/upload/index.js"
    click MergeEntrypoint "https://github.com/actions/upload-artifact/blob/main/dist/merge/index.js"
    click UInputHelper "https://github.com/actions/upload-artifact/blob/main/src/upload/input-helper.ts"
    click MInputHelper "https://github.com/actions/upload-artifact/blob/main/src/merge/input-helper.ts"
    click UInputs "https://github.com/actions/upload-artifact/blob/main/src/upload/upload-inputs.ts"
    click MInputs "https://github.com/actions/upload-artifact/blob/main/src/merge/merge-inputs.ts"
    click FileDiscovery "https://github.com/actions/upload-artifact/blob/main/src/shared/search.ts"
    click ArtifactClient "https://github.com/actions/upload-artifact/blob/main/src/shared/upload-artifact.ts"
    click UploadLogic "https://github.com/actions/upload-artifact/blob/main/src/upload/upload-artifact.ts"
    click MergeLogic "https://github.com/actions/upload-artifact/blob/main/src/merge/merge-artifacts.ts"
    click ActionYML "https://github.com/actions/upload-artifact/blob/main/action.yml"
    click MergeYML "https://github.com/actions/upload-artifact/blob/main/merge/action.yml"
    click MergeYML "https://github.com/actions/upload-artifact/blob/main/merge/README.md"
    click UploadEntrypoint "https://github.com/actions/upload-artifact/tree/main/dist/upload/"
    click MergeEntrypoint "https://github.com/actions/upload-artifact/tree/main/dist/merge/"

    %% Styles
    classDef module fill:#D6EAF8,stroke:#2980B9,color:#1B4F72;
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#196F3D;
    classDef datastore fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
```
