How actions/upload-artifact works
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)