Proposal: add support for artifact aliasing - #419
Merged
Conversation
This document proposes artifact aliasing in Bazel, allowing content to be addressable under multiple exec paths without copying. It details the API, semantics, and implications for backward compatibility and laydown strategies.
thesayyn
added a commit
to thesayyn/bazel
that referenced
this pull request
Jul 21, 2026
Adds ctx.actions.copy(output, target_file): makes target_file's content available at output (a second exec path), sharing its digest, with no byte copy and no spawn. Unlike ctx.actions.symlink, which plants a followable symbolic link that resolves back to the target's location, ctx.actions.copy only declares the relationship and defers materialization to sandbox/spawn creation -- the execution strategy places the target's content at the output's own path (hard link, copy, or the shared digest on remote execution), so its realpath stays inside the consuming tree (which tools such as Node.js require). Strategies that cannot materialize content (a purely symlinking sandbox or non-sandboxed local execution) fall back to a symlink. The original is never a declared input of the consumer -- it sees only the copy. Reuses the existing resolved-path metadata rather than adding new machinery: FileArtifactValue.isContentCopy() marks the value (ordinary symlinks are unchanged), a declaration-only CopyAction injects it, and the remote prefetcher and the local sandbox stage the content from the recorded source. Design: bazelbuild/proposals#419
2 tasks
thesayyn
added a commit
to thesayyn/bazel
that referenced
this pull request
Jul 21, 2026
Adds ctx.actions.copy(output, target_file): makes target_file's content available at output (a second exec path), sharing its digest, with no byte copy and no spawn. Unlike ctx.actions.symlink, which plants a followable symbolic link that resolves back to the target's location, ctx.actions.copy only declares the relationship and defers materialization to sandbox/spawn creation -- the execution strategy places the target's content at the output's own path (hard link, copy, or the shared digest on remote execution), so its realpath stays inside the consuming tree (which tools such as Node.js require). Strategies that cannot materialize content (a purely symlinking sandbox or non-sandboxed local execution) fall back to a symlink. The original is never a declared input of the consumer -- it sees only the copy. Reuses the existing resolved-path metadata rather than adding new machinery: FileArtifactValue.isContentCopy() marks the value (ordinary symlinks are unchanged), a declaration-only CopyAction injects it, and the remote prefetcher and the local sandbox stage the content from the recorded source. Design: bazelbuild/proposals#419
thesayyn
added a commit
to thesayyn/bazel
that referenced
this pull request
Jul 21, 2026
Adds ctx.actions.copy(output, target_file): makes target_file's content available at output (a second exec path), sharing its digest, with no byte copy and no spawn. Unlike ctx.actions.symlink, which plants a followable symbolic link that resolves back to the target's location, ctx.actions.copy only declares the relationship and defers materialization to sandbox/spawn creation -- the execution strategy places the target's content at the output's own path (hard link, copy, or the shared digest on remote execution), so its realpath stays inside the consuming tree (which tools such as Node.js require). Strategies that cannot materialize content (a purely symlinking sandbox or non-sandboxed local execution) fall back to a symlink. The original is never a declared input of the consumer -- it sees only the copy. Reuses the existing resolved-path metadata rather than adding new machinery: FileArtifactValue.isContentCopy() marks the value (ordinary symlinks are unchanged), a declaration-only CopyAction injects it, and the remote prefetcher and the local sandbox stage the content from the recorded source. Design: bazelbuild/proposals#419
thesayyn
added a commit
to thesayyn/bazel
that referenced
this pull request
Jul 21, 2026
Adds ctx.actions.copy(output, target_file): makes target_file's content available at output (a second exec path), sharing its digest, with no byte copy and no spawn. Unlike ctx.actions.symlink, which plants a followable symbolic link that resolves back to the target's location, ctx.actions.copy only declares the relationship and defers materialization to sandbox/spawn creation -- the execution strategy places the target's content at the output's own path (hard link, copy, or the shared digest on remote execution), so its realpath stays inside the consuming tree (which tools such as Node.js require). Strategies that cannot materialize content (a purely symlinking sandbox or non-sandboxed local execution) fall back to a symlink. The original is never a declared input of the consumer -- it sees only the copy. Reuses the existing resolved-path metadata rather than adding new machinery: FileArtifactValue.isContentCopy() marks the value (ordinary symlinks are unchanged), a declaration-only CopyAction injects it, and the remote prefetcher and the local sandbox stage the content from the recorded source. Design: bazelbuild/proposals#419
thesayyn
added a commit
to thesayyn/bazel
that referenced
this pull request
Jul 21, 2026
Adds ctx.actions.copy(output, target_file): makes target_file's content available at output (a second exec path), sharing its digest, with no byte copy and no spawn. Unlike ctx.actions.symlink, which plants a followable symbolic link that resolves back to the target's location, ctx.actions.copy only declares the relationship and defers materialization to sandbox/spawn creation -- the execution strategy places the target's content at the output's own path (hard link, copy, or the shared digest on remote execution), so its realpath stays inside the consuming tree (which tools such as Node.js require). Strategies that cannot materialize content (a purely symlinking sandbox or non-sandboxed local execution) fall back to a symlink. The original is never a declared input of the consumer -- it sees only the copy. Reuses the existing resolved-path metadata rather than adding new machinery: FileArtifactValue.isContentCopy() marks the value (ordinary symlinks are unchanged), a declaration-only CopyAction injects it, and the remote prefetcher and the local sandbox stage the content from the recorded source. Design: bazelbuild/proposals#419
thesayyn
added a commit
to thesayyn/bazel
that referenced
this pull request
Jul 21, 2026
Adds ctx.actions.copy(output, target_file): makes target_file's content available at output (a second exec path), sharing its digest, with no byte copy and no spawn. Unlike ctx.actions.symlink, which plants a followable symbolic link that resolves back to the target's location, ctx.actions.copy only declares the relationship and defers materialization to sandbox/spawn creation -- the execution strategy places the target's content at the output's own path (hard link, copy, or the shared digest on remote execution), so its realpath stays inside the consuming tree (which tools such as Node.js require). Strategies that cannot materialize content (a purely symlinking sandbox or non-sandboxed local execution) fall back to a symlink. The original is never a declared input of the consumer -- it sees only the copy. Reuses the existing resolved-path metadata rather than adding new machinery: FileArtifactValue.isContentCopy() marks the value (ordinary symlinks are unchanged), a declaration-only CopyAction injects it, and the remote prefetcher and the local sandbox stage the content from the recorded source. Design: bazelbuild/proposals#419
fmeum
reviewed
Jul 21, 2026
Add artifact aliasing proposal with API and semantics.
thesayyn
changed the title
Explain how tree aliases handle symlinks and content staging.
Contributor
|
Why not link this from the main list in |
|
potentially duplicated of #396 ? |
Open
Contributor
Author
Contributor
Author
Will do, i missed that. |
Contributor
Far be it from me to be overly critical, but you haven't yet? |
Contributor
Author
|
Fixed, and fixed an earlier issue with sandbox proposal. thanks @lberki Don't mind me asking, what's the next step to get this to be accepted? |
lberki
approved these changes
Jul 23, 2026
Contributor
|
We'll have to find a reviewer (and some capacity to review the change). Let me see what I can do. |
Contributor
|
Since this was sent as Markdown and not as a Google doc, should we comment on this PR or create a separate GitHub discussion? There is precedent for both :-) Edit: Left some early general comments here: #396 (comment) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This document proposes artifact aliasing in Bazel, allowing content to be addressable under multiple exec paths without copying. It details the API, semantics, and implications for backward compatibility and laydown strategies.