feat: install Atmos from a branch or tag with --use-version=ref:<name>#2569
Merged
Conversation
Add a `ref:` version spec to `--use-version` (and `version.use` / ATMOS_USE_VERSION) that resolves a git branch or tag to its latest commit's CI build artifact, e.g. `atmos --use-version=ref:main version`. - pkg/toolchain/version_spec.go: new VersionTypeRef, `ref:` parsing, IsRefVersion, light ref validation - pkg/github/artifacts.go: RepositoriesService + GetRefSHA resolves a ref to its full commit SHA via GetCommitSHA1 (regenerated mock) - pkg/toolchain/ref_artifact.go: ResolveRef wrapper with friendly errors - pkg/version/reexec.go: wire ResolveRef into ReexecConfig; ref always re-execs, resolves to a SHA, then reuses the existing SHA install/cache path, and fails hard on resolution errors - docs, blog post, and roadmap milestone (minor) The ref is re-resolved on every run so a mutable branch like `main` tracks the latest build, while the SHA-keyed cache avoids reinstalling when the ref has not moved. Resolving to the full SHA also sidesteps the GitHub head_sha filter requiring a full (not short) SHA. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
requested a review
from a team
as a code owner
Contributor
|
Tip Atmos Pro
No affected stacks workflow was detected for this pull request. 
|
Erik Osterman (Cloud Posse) (osterman)
added
the
minor
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
🚧 Files skipped from review as they are similar to previous changes (4)
📝 WalkthroughWalkthroughAdds support for ChangesGit ref-to-SHA resolution for --use-version flag
Sequence Diagram(s)The hidden review stack above includes a sequence diagram that visualizes: GetRefSHA → RepositoriesService commit lookup (success / not-found / empty), and the artifact-run lookup flow that iterates newest-first Tests runs and checks artifacts per run. Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pkg/github/artifacts.go`:
- Around line 117-121: The ArtifactFetcher struct's repositories field is not
being initialized in NewArtifactFetcher, causing GetRefSHA to nil-dereference;
update the constructor NewArtifactFetcher to accept and assign a
RepositoriesService (or pass an existing repositories dependency) into the
ArtifactFetcher.repositories field so any calls to GetRefSHA use a valid service
instance; ensure all constructor call sites that build ArtifactFetcher (and any
similar factory functions around lines referenced) are updated to provide the
repositories dependency.
In `@pkg/version/reexec.go`:
- Around line 450-454: The code calls cfg.ResolveRef unguarded in
findOrInstallRefVersionWithConfig which can panic if ResolveRef is nil on a
partial ReexecConfig; update findOrInstallRefVersionWithConfig to check cfg !=
nil and cfg.ResolveRef != nil before invoking ResolveRef, and if missing return
a clear typed error (e.g., ErrResolveRefUnavailable or a descriptive
install/config error) so callers get a proper error instead of a nil-func panic;
reference the findOrInstallRefVersionWithConfig function and the
ReexecConfig.ResolveRef field when making this change.
In `@website/src/data/roadmap.js`:
- Line 449: The shipped milestone object for "Branch and tag installation via
--use-version (ref:)" in website/src/data/roadmap.js is missing the required pr
metadata and the initiative progress needs updating; add a pr: <PR_NUMBER> field
to that milestone object (alongside existing status: 'shipped' and changelog:
'use-version-ref') and then update the corresponding initiative's progress
percentage to reflect this shipped item so the roadmap metadata contract is
satisfied.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: fb56167f-9edc-4451-b902-e3ac411ff39c
📒 Files selected for processing (12)
pkg/github/artifacts.gopkg/github/artifacts_test.gopkg/github/mock_artifacts_test.gopkg/toolchain/ref_artifact.gopkg/toolchain/ref_artifact_test.gopkg/toolchain/version_spec.gopkg/toolchain/version_spec_test.gopkg/version/reexec.gopkg/version/reexec_test.gowebsite/blog/2026-06-04-use-version-ref.mdxwebsite/docs/cli/configuration/version/use.mdxwebsite/src/data/roadmap.js
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #2569 +/- ##
==========================================
+ Coverage 78.87% 78.91% +0.03%
==========================================
Files 1197 1198 +1
Lines 114715 114797 +82
==========================================
+ Hits 90485 90594 +109
+ Misses 19261 19235 -26
+ Partials 4969 4968 -1
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
Add the pr reference to the shipped "Branch and tag installation via --use-version (ref:)" roadmap milestone, per CodeRabbit review. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… completes `--use-version=pr:`, `sha:`, and `ref:` re-exec by downloading the Atmos build artifact for a commit. The run finder filtered workflow runs on `Status: "completed"`, but GitHub only marks the "Tests" run completed once every job finishes — including the ~20-min acceptance-test matrix. So even though the Build job had already uploaded the binary in ~6 min, the artifact was invisible and install failed with "tool not found / CI build may be failing". Gate on artifact availability instead of run completion: replace findCompletedWorkflowRun with findRunWithArtifact, which includes in-progress runs and returns the most recent "Tests" run that actually has the platform artifact uploaded (falling back to an older run on re-runs). One shared finder fixes all three --use-version modes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Document the ref:/sha: version-install test functions with godoc-style summaries describing what each verifies, and promote a few inline comments to doc comments. No behavior change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Andriy Knysh (aknysh)
approved these changes
Jun 5, 2026
Contributor
|
Tip Atmos Pro
No affected stacks workflow was detected for this pull request.
|
|
These changes were released in v1.221.0-rc.5. |
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
2 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.
what
ref:<name>version spec to--use-version(andversion.useinatmos.yaml/ATMOS_USE_VERSION) that installs Atmos from the latest commit of a branch or tag, e.g.atmos --use-version=ref:main version.ref:main,ref:release/v1.199,ref:v1.199.0,ref:heads/main,ref:tags/v1.199.0.sha:install/cache path unchanged; ref versions always re-execute and fail hard on resolution errors.version/use.mdx), aminorblog post, and a roadmap milestone.why
--use-versiononly accepted PR numbers (pr:1234), commit SHAs (sha:ceb7526), and releases — a branch name likemainwas rejected, even though branch/tag pushes already publish the samebuild-artifacts-*from theTestsworkflow.ref:lets you pin a moving target once (ref:main) instead of chasing a newsha:after every merge, making it trivial to test unreleased fixes on a branch.head_shafilter, which only matches full (not short) SHAs.references
website/blog/2026-06-04-use-version-ref.mdxSummary by CodeRabbit
New Features
Behavior Changes
Bug Fixes
Documentation