# actions/action-versions architecture

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

- Interactive diagram: https://gitdiagram.com/actions/action-versions
- Repository: https://github.com/actions/action-versions

## Overview

##### Project type and purpose
- This is an open-source tooling project that provides a local cache of first-party GitHub Actions on a self-hosted runner.
- Its purpose is to download, pin, and store popular first-party actions (e.g., actions/checkout, actions/setup-node) so that workflow runs can pull them locally rather than from the GitHub Actions marketplace, improving speed and reliability.

##### File structure
- Top‐level directories:
- .github: CI workflows, contributing guidelines, code of conduct
- config/actions: JSON files listing which actions and refs to cache
- script: Core CLI and helper scripts in Bash and Node.js
- Within script/:
- script/add-action.sh, build.sh, update-action.sh: entry points for adding or updating cached actions
- script/internal: reusable JS modules (git.js, https.js, fs-helper.js, etc.) and shell helpers
- script/generated: auto-generated wrappers for GitHub Actions toolkit scripts
- Config files drive behavior (which refs to include), build/test scripts ensure integrity, workflows in .github/ci.yml run tests and updates.

##### Pull additional insights from the README
- The cache is pinned by commit SHA and excludes preview releases (beta).
- Users invoke add-action.sh or update-action.sh to refresh or add action versions.
- Maintainers rely on automated workflows to keep the cache definitions up to date.

##### Final advice
- Be very detailed: break out each script and internal‐library as separate subcomponents if it aids clarity.
- Flow from configuration to cache creation to action consumption.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    GithubAPI["GitHub API"]:::external

    %% Data Stores
    ConfigStore["Config Store\n(JSON files)"]:::datastore
    click ConfigStore "https://github.com/actions/action-versions/tree/main/config/actions/"
    LocalCache["Local Actions Cache\n(directory)"]:::datastore

    %% Processes
    Runner["GitHub Actions Runner"]:::process

    subgraph "CLI Scripts" 
        AddAction["add-action.sh"]:::process
        click AddAction "https://github.com/actions/action-versions/blob/main/script/add-action.sh"
        UpdateAction["update-action.sh"]:::process
        click UpdateAction "https://github.com/actions/action-versions/blob/main/script/update-action.sh"
        BuildScript["build.sh"]:::process
        click BuildScript "https://github.com/actions/action-versions/blob/main/script/build.sh"
        CreatePR["create-pull-request.sh"]:::process
        click CreatePR "https://github.com/actions/action-versions/blob/main/script/create-pull-request.sh"
        TestScript["test.sh"]:::process
        click TestScript "https://github.com/actions/action-versions/blob/main/script/test.sh"
        VerifyClean["verify-no-unstaged-changes.sh"]:::process
        click VerifyClean "https://github.com/actions/action-versions/blob/main/script/verify-no-unstaged-changes.sh"

        subgraph "Internal Libraries"
            InternalDir["script/internal"]:::process
            click InternalDir "https://github.com/actions/action-versions/tree/main/script/internal/"
        end

        subgraph "Generated Action Wrappers"
            GeneratedDir["script/generated"]:::process
            click GeneratedDir "https://github.com/actions/action-versions/tree/main/script/generated/"
        end
    end

    subgraph "CI Workflows"
        CIci["ci.yml"]:::process
        click CIci "https://github.com/actions/action-versions/blob/main/.github/workflows/ci.yml"
        CIupdate["update.yml"]:::process
        click CIupdate "https://github.com/actions/action-versions/blob/main/.github/workflows/update.yml"
    end

    %% Data and control flows
    AddAction -->|"read config"| ConfigStore
    UpdateAction -->|"read config"| ConfigStore
    AddAction --> InternalDir
    UpdateAction --> InternalDir
    InternalDir -->|"fetch refs"| GithubAPI
    InternalDir -->|"clone/download"| LocalCache

    Runner -->|"resolve actions"| LocalCache

    CIci --> BuildScript
    CIci --> TestScript
    CIci -->|"validate and lint"| ConfigStore

    CIupdate --> UpdateAction
    CIupdate --> CreatePR
    CIupdate -->|"update config files"| ConfigStore

    %% Styles
    classDef external fill:#B3CDE3,stroke:#03396C,color:#03396C;
    classDef datastore fill:#FFF3B0,stroke:#D4A017,color:#D4A017;
    classDef process fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32;
```
