AGENT SKILL

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

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, Artifact and GitHubCacheBlobStore all need ACTIONS_RESULTS_URL/ACTIONS_RUNTIME_TOKEN, which the runner injects only into action execution contexts, not run: shell steps. BlobStore.layerS3 and ToolInstaller need neither and work identically from either.
  • Pass ActionCache's literal glob pattern list to both save and restore. save resolves 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. HttpClient for downloads, ChildProcessSpawner for archive extraction, FileSystem for 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.install can answer an ambient package manager with no binDir — a consumer that always reads binDir breaks on that branch. See references/installers.md.
  • A hex-fed hash accumulator in CacheKey.hashFiles produces a plausible-looking digest that never matches any cache entry written by @actions/glob's hashFiles — the per-file digest must feed the accumulator as binary. See references/cache-and-keys.md.
  • Resolved cache paths reaching tar via argv instead of a manifest file blow past the OS argv limit on a large glob resolution. See references/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. See references/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, and CacheKey's restore-key ladder, hashFiles byte-compatibility and matchingFiles discovery. 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 reports misconfigured, 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 the node:-import accounting for this tier. Load when: installing a toolchain or an exact package-manager version, or reviewing a node: import in this package.

04 同仓库更多 Skills

spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8