actions-cache-and-artifacts
Use when caching a dependency directory in a GitHub Action, uploading or downloading a workflow artifact, installing a toolchain or an exact package-manager version into the runner's tool cache, or storing a keyed blob against the Actions cache or an S3-compatible bucket.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- actions-cache-and-artifacts
- description
- Use when caching a dependency directory in a GitHub Action, uploading or downloading a workflow artifact, installing a toolchain or an exact package-manager version into the runner's tool cache, or storing a keyed blob against the Actions cache or an S3-compatible bucket.
- when_to_use
- ACTIONS_RESULTS_URL, ACTIONS_RUNTIME_TOKEN, tool cache, blob store, ActionCache, Artifact, GitHubCacheBlobStore, BlobStore, S3Config, ToolInstaller, PackageManagerInstaller, CacheKey, hashFiles, restore keys, withNamespace, cache bust, stage-then-swap, Twirp retry, @azure/storage-blob confinement
02 资源文件 3
- 参考文档references/blob-stores.md12.1 KB
- 参考文档references/cache-and-keys.md5.6 KB
- 参考文档references/installers.md7.7 KB
03 SKILL.md 正文
Actions cache and artifacts
The storage tier of @effected/github-actions: caches, artifacts, blobs, and installed tools. @actions/cache and @actions/artifact are both re-implemented directly against their own HTTP protocols rather than taken as dependencies — either one alone drags a tree larger than this whole package.
For the general Effect v4 service/layer rules this package follows — Context.Service, provideMerge vs mergeAll, memoization by reference — see effect-v4-services-layers; this skill carries only the storage-specific instance of each.
What you have
| Need | Service | Layer | R (besides itself) |
Error |
|---|---|---|---|---|
| Archive and restore a dependency directory across jobs | ActionCache |
ActionCache.layer |
ActionEnvironment | HttpClient | FileSystem | Path | ChildProcessSpawner |
ActionCacheError |
| Upload, list, get, download or delete a workflow artifact | Artifact |
Artifact.layer |
same five | ArtifactError |
| A keyed blob with caller-owned metadata, in the Actions cache | BlobStore over GitHubCacheBlobStore.layer |
GitHubCacheBlobStore.layer |
HttpClient | ActionEnvironment |
BlobStoreError | BlobEnvelopeError |
| Same, in S3 / R2 / MinIO / Spaces | BlobStore over BlobStore.layerS3(config) |
BlobStore.layerS3(config) |
HttpClient | ActionOutputs | Digest.Digest | Mac.Mac |
same |
A cache key, its restore-key ladder, and hashFiles |
CacheKey |
none — a pure Schema.Class with Effect.fn statics |
FileSystem (hashFiles), + Path (matchingFiles) |
CacheKeyError |
| Download, extract and cache a toolchain | ToolInstaller |
ToolInstaller.layer |
ActionEnvironment | FileSystem | Path | HttpClient | ChildProcessSpawner |
ToolInstallerError |
| Pin and install an exact npm/pnpm/bun on the runner | PackageManagerInstaller |
PackageManagerInstaller.layer |
ActionEnvironment | FileSystem | Path | ChildProcessSpawner | ToolInstaller |
PackageManagerInstallerError |
ActionRuntime.layer provides none of the six services above by default — see actions-runtime for why, and for the one-line cost of taking one (Action.run(program, { layer: ActionCache.layer })).
Standards
- Take a storage service as an explicit one-line extra layer — never expect one from
ActionRuntime.layer. Their requirements are already satisfied by the runtime's own services; the runtime simply doesn't provide them by default. - Only reach the Actions results backend from a
uses:step.ActionCache,ArtifactandGitHubCacheBlobStoreall needACTIONS_RESULTS_URL/ACTIONS_RUNTIME_TOKEN, which the runner injects only into action execution contexts, notrun:shell steps.BlobStore.layerS3andToolInstallerneed neither and work identically from either. - Pass
ActionCache's literal glob pattern list to bothsaveandrestore.saveresolves patterns before archiving, but the cache version on both sides hashes the literal pattern list, not the resolved paths — a mismatched literal list makes a saved entry invisible on restore. - Never share a heavy-dependency adapter through an internal helper. Each Azure-touching module carries its own small adapter rather than importing one from a shared module — a consumer that imports only a light service must be structurally unable to link the heavy dependency into its bundle.
- Stage into a temp directory under the cache root, then rename into place — never copy straight to a tool's final destination. A copy left partial by a failure looks like a completed install to a directory-presence check, and every later run then uses a broken toolchain silently.
- Read both the camelCase and snake_case spelling of a field from an internal, reverse-engineered wire response, and key retry on a structural
kind, never a formatted message substring — a reworded error string must never become a silent policy change in what gets retried. - Let everything that can go through a core contract do so.
HttpClientfor downloads,ChildProcessSpawnerfor archive extraction,FileSystemfor reading file contents —node:imports in this tier are licensed only for what core genuinely cannot do yet (HMAC, gzip framing), never as a blanket substitute.
Footguns
PackageManagerInstaller.installcan answer an ambient package manager with nobinDir— a consumer that always readsbinDirbreaks on that branch. Seereferences/installers.md.- A hex-fed hash accumulator in
CacheKey.hashFilesproduces a plausible-looking digest that never matches any cache entry written by@actions/glob'shashFiles— the per-file digest must feed the accumulator as binary. Seereferences/cache-and-keys.md. - Resolved cache paths reaching
tarvia argv instead of a manifest file blow past the OS argv limit on a large glob resolution. Seereferences/cache-and-keys.md. - A legacy, unframed blob decodes as a typed clean miss against
BlobEnvelope, on purpose — treat it as "not cached yet," never as a corrupt read. Seereferences/blob-stores.md. - The Actions-cache Twirp protocol hands back an Azure blob URL for the payload, so the Azure-touching module count is three, not the two a casual read of the cache/artifact split suggests. See
references/blob-stores.md.
Additional resources
- references/cache-and-keys.md —
ActionCache's glob-vs-literal path handling in full, the manifest-file tar invocation, andCacheKey's restore-key ladder,hashFilesbyte-compatibility andmatchingFilesdiscovery. Load when: designing a cache step, a restore-key fallback policy, or a file-hash-derived key. - references/blob-stores.md — the results-backend confinement rule,
BlobEnvelope's wire format and error union in full, the Azure three-module confinement with its reachability test, the transport seam (FileBlobTransfer/DataBlobTransfer), and the Twirp field-spelling and retry discipline. Load when: storing a keyed blob, reviewing why a cache/artifact call reportsmisconfigured, or auditing the Azure import boundary. - references/installers.md —
ToolInstaller's stage-then-swap cache write, its layout contract with the runner,PackageManagerInstaller's ambient-vs-cached branch, and thenode:-import accounting for this tier. Load when: installing a toolchain or an exact package-manager version, or reviewing anode:import in this package.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.