Skip to content

Add support for $GITHUB_ARTIFACTS environment files#4527

Draft
bdehamer wants to merge 1 commit into
actions:mainfrom
bdehamer:bdehamer-artifacts
Draft

Add support for $GITHUB_ARTIFACTS environment files#4527
bdehamer wants to merge 1 commit into
actions:mainfrom
bdehamer:bdehamer-artifacts

Conversation

@bdehamer

Copy link
Copy Markdown

Summary

Adds support for two new per-job environment files that let workflow steps declare build artifacts and read back the aggregated set:

  • $GITHUB_ARTIFACTS (write side) — a step appends artifact references (local file paths or OCI subject references). The runner parses each entry, validates it, computes a digest for local files, and aggregates the results at job scope.
  • $GITHUB_ARTIFACTS_LIST (read side) — the runner populates a JSON document enumerating every artifact subject declared so far in the job, so downstream steps can consume the canonical set.

The feature is gated behind the actions_runner_allow_artifacts_file feature flag (with an ACTIONS_RUNNER_ALLOW_ARTIFACTS_FILE environment-variable fallback) and is off by default.

Changes

New files

  • CreateArtifactsFileCommand.cs — Write-side handler for $GITHUB_ARTIFACTS. Parses and validates each entry, computes SHA-256 digests for local files (resolved relative to the workspace root), and aggregates subjects at job scope with de-duplication, conflicting-digest detection, a 1 MiB file-size cap, and a 500-artifact aggregate cap.
  • ArtifactsListFileCommand.cs — Read-side handler that populates $GITHUB_ARTIFACTS_LIST with a versioned JSON document ({ version, subjects: [{ name, digest, kind }] }).
  • ArtifactSubject.cs — Subject model (Name, Digest, Kind) shared by both commands.
  • CreateArtifactsFileCommandL0.cs, ArtifactsListFileCommandL0.cs — Unit tests covering parsing, validation, digest computation, aggregation, de-dup/conflict handling, and list serialization.

Modified files

  • FileCommandManager.cs — Adds a PopulateInitialContents hook (default no-op) so the list command can seed $GITHUB_ARTIFACTS_LIST before step execution; covered by FileCommandManagerL0.cs.
  • ExtensionManager.cs — Registers the two new file commands.
  • GlobalContext.cs / ExecutionContext.cs — Adds the job-scoped ArtifactSubjects aggregate, keyed by canonical subject name.
  • GitHubContext.cs — Exposes the artifacts and artifacts_list context entries.
  • Constants.cs — Adds the AllowArtifactsFile feature flag and the artifact command error messages.

Key design decisions

  • Workspace-relative path resolution — Relative file paths in $GITHUB_ARTIFACTS are always resolved against GITHUB_WORKSPACE rather than a step's working-directory, matching the precedent set by hashFiles() and problem matchers.
  • Job-scoped aggregation — Subjects are accumulated across all steps in the job and de-duplicated by canonical name; re-declaring a name with a different digest is a hard error.
  • Feature-flagged and off by default — Gated by actions_runner_allow_artifacts_file with an env-var fallback, so the behavior is opt-in until rollout.

Signed-off-by: Brian DeHamer <bdehamer@github.com>
@bdehamer bdehamer force-pushed the bdehamer-artifacts branch from 4930e1d to 9a64d83 Compare June 26, 2026 22:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant