fix: the package replace logic when using tag, branch or commit (#2299)

## Description Fix the package replace logic when using tag, branch or commit The current issue is the `package replace logic` fails when you add a tag, branch or commit in the replace value, like this example: `replace: - github.com/kurtosis-tech/ethereum-package: github.com/kurtosis-tech/ethereum-package@da55be84861e93ce777076e545abee35ff2d51ce` If we see the evaluation error `Evaluation error: An error occurred while loading the module 'github.com/kurtosis-tech/ethereum-package@da55be84861e93ce777076e545abee35ff2d51ce/src/package_io/input_parser.star' Caused by: '/input_parser.star' doesn't exist in the package 'kurtosis-tech/ethereum-package' at [github.com/kurtosis-tech/ethereum-package@da55be84861e93ce777076e545abee35ff2d51ce/main.star:1:29]: <toplevel> at [github.com/kurtosis-tech/awesome-kurtosis/chainlink-node/main.star:2:33]: <toplevel>` we understand it's trying to import the file from this path `github.com/kurtosis-tech/ethereum-package@da55be84861e93ce777076e545abee35ff2d51ce` and it doesn't exist because the folder, inside the APIC file system, is created without the hash, it's `github.com/kurtosis-tech/ethereum-package` This is happening because an absolute locator like this `github.com/kurtosis-tech/ethereum-package/src/package_io/input_parser.star` does not incorporate the concept of hash, branch or commit. The fix is incorporated the concept of `hash, branch or commit` in a new AbsoluteLocator object, so this way we can specify if the absolute locator is pointing to other place than the main branch. With this change we can accept the `github.com/kurtosis-tech/ethereum-package@da55be84861e93ce777076e545abee35ff2d51ce` replace value and an absolute locator string like this `github.com/kurtosis-tech/ethereum-package@da55be84861e93ce777076e545abee35ff2d51ce/src/package_io/input_parser.star` will be represented with an AbsoluteLocator object with locator `github.com/kurtosis-tech/ethereum-package/src/package_io/input_parser.star` and and tagBranchOrCommit `da55be84861e93ce777076e545abee35ff2d51ce` We already had support for retrieving packages from different tag, branch or commit but only for `packageId` values and not for `absolute locators` ## REMINDER: Tag Reviewers, so they get notified to review ## Is this change user facing? YES ## References (if applicable) Fix #2279
kurtosis-tech · Mar 15, 2024 · 1abcdcc · 1abcdcc
1 parent f54c2e8
commit 1abcdcc
Show file tree

Hide file tree

Showing 23 changed files with 370 additions and 176 deletions.
diff --git a/api/golang/core/lib/shared_utils/parsed_git_url.go b/api/golang/core/lib/shared_utils/parsed_git_url.go
@@ -108,7 +108,7 @@ func ParseGitURL(packageURL string) (*ParsedGitURL, error) {
 		return nil, stacktrace.NewError("Error parsing the URL of module. We only support modules on Github for now but got '%v'", packageURL)
 	}
 
-	pathWithoutVersion, maybeTagBranchOrCommit := parseOutTagBranchOrCommit(parsedURL.Path)
+	pathWithoutVersion, maybeTagBranchOrCommit := ParseOutTagBranchOrCommit(parsedURL.Path)
 
 	splitURLPath := cleanPathAndSplit(pathWithoutVersion)
 
@@ -151,8 +151,8 @@ func cleanPathAndSplit(urlPath string) []string {
 	return sliceWithoutEmptyStrings
 }
 
-// parseOutTagBranchOrCommit splits the string around "@" and then split the after string around "/"
-func parseOutTagBranchOrCommit(input string) (string, string) {
+// ParseOutTagBranchOrCommit splits the string around "@" and then split the after string around "/"
+func ParseOutTagBranchOrCommit(input string) (string, string) {
 	cleanInput := path.Clean(input)
 	pathWithoutVersion, maybeTagBranchOrCommitWithFile, _ := strings.Cut(cleanInput, tagBranchOrCommitDelimiter)
 

diff --git a/core/server/api_container/server/startosis_engine/builtins/import_module/import_module.go b/core/server/api_container/server/startosis_engine/builtins/import_module/import_module.go
@@ -78,11 +78,12 @@ func (builtin *importModuleCapabilities) Interpret(locatorOfModuleInWhichThisBui
 		return nil, explicitInterpretationError(err)
 	}
 	relativeOrAbsoluteModuleLocator := moduleLocatorArgValue.GoString()
-	absoluteModuleLocator, relativePathParsingInterpretationErr := builtin.packageContentProvider.GetAbsoluteLocator(builtin.packageId, locatorOfModuleInWhichThisBuiltInIsBeingCalled, relativeOrAbsoluteModuleLocator, builtin.packageReplaceOptions)
+	absoluteModuleLocatorObj, relativePathParsingInterpretationErr := builtin.packageContentProvider.GetAbsoluteLocator(builtin.packageId, locatorOfModuleInWhichThisBuiltInIsBeingCalled, relativeOrAbsoluteModuleLocator, builtin.packageReplaceOptions)
 	if relativePathParsingInterpretationErr != nil {
 		return nil, relativePathParsingInterpretationErr
 	}
-	logrus.Debugf("importing module from absolute locator '%s'", absoluteModuleLocator)
+	absoluteModuleLocator := absoluteModuleLocatorObj.GetLocator()
+	logrus.Debugf("importing module from absolute locator '%s' with tag, branch or commit %s", absoluteModuleLocator, absoluteModuleLocatorObj.GetTagBranchOrCommit())
 
 	var loadInProgress *startosis_packages.ModuleCacheEntry
 	cacheEntry, found := builtin.moduleGlobalCache[absoluteModuleLocator]
@@ -102,7 +103,7 @@ func (builtin *importModuleCapabilities) Interpret(locatorOfModuleInWhichThisBui
 	}()
 
 	// Load it.
-	contents, interpretationError := builtin.packageContentProvider.GetModuleContents(absoluteModuleLocator)
+	contents, interpretationError := builtin.packageContentProvider.GetModuleContents(absoluteModuleLocatorObj)
 	if interpretationError != nil {
 		return nil, startosis_errors.WrapWithInterpretationError(interpretationError, "An error occurred while loading the module '%v'", absoluteModuleLocator)
 	}

diff --git a/core/server/api_container/server/startosis_engine/builtins/read_file/read_file.go b/core/server/api_container/server/startosis_engine/builtins/read_file/read_file.go
@@ -55,11 +55,11 @@ func (builtin *readFileCapabilities) Interpret(locatorOfModuleInWhichThisBuiltIn
 		return nil, startosis_errors.WrapWithInterpretationError(err, "Unable to extract value for arg '%s'", srcValue)
 	}
 	fileToReadStr := srcValue.GoString()
-	fileToReadStr, relativePathParsingInterpretationErr := builtin.packageContentProvider.GetAbsoluteLocator(builtin.packageId, locatorOfModuleInWhichThisBuiltInIsBeingCalled, fileToReadStr, builtin.packageReplaceOptions)
+	absoluteLocator, relativePathParsingInterpretationErr := builtin.packageContentProvider.GetAbsoluteLocator(builtin.packageId, locatorOfModuleInWhichThisBuiltInIsBeingCalled, fileToReadStr, builtin.packageReplaceOptions)
 	if relativePathParsingInterpretationErr != nil {
 		return nil, relativePathParsingInterpretationErr
 	}
-	packageContent, interpretationErr := builtin.packageContentProvider.GetModuleContents(fileToReadStr)
+	packageContent, interpretationErr := builtin.packageContentProvider.GetModuleContents(absoluteLocator)
 	if interpretationErr != nil {
 		return nil, interpretationErr
 	}

diff --git a/...artosis_engine/kurtosis_starlark_framework/test_engine/image_build_spec_framework_test.go b/...artosis_engine/kurtosis_starlark_framework/test_engine/image_build_spec_framework_test.go
@@ -20,10 +20,10 @@ func (suite *KurtosisTypeConstructorTestSuite) TestImageBuildSpecTest() {
 	suite.packageContentProvider.EXPECT().
 		GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testBuildContextDir, testNoPackageReplaceOptions).
 		Times(1).
-		Return(testBuildContextLocator, nil)
+		Return(testBuildContextAbsoluteLocator, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePackageFilePath(testContainerImageLocator).
+		GetOnDiskAbsolutePackageFilePath(testContainerImageAbsoluteLocator).
 		Times(1).
 		Return(testOnDiskContainerImagePath, nil)
 

diff --git a/...urtosis_starlark_framework/test_engine/image_build_spec_framework_with_build_args_test.go b/...urtosis_starlark_framework/test_engine/image_build_spec_framework_with_build_args_test.go
@@ -20,10 +20,10 @@ func (suite *KurtosisTypeConstructorTestSuite) TestImageBuildSpecWithBuildArgsTe
 	suite.packageContentProvider.EXPECT().
 		GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testBuildContextDir, testNoPackageReplaceOptions).
 		Times(1).
-		Return(testBuildContextLocator, nil)
+		Return(testBuildContextAbsoluteLocator, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePackageFilePath(testContainerImageLocator).
+		GetOnDiskAbsolutePackageFilePath(testContainerImageAbsoluteLocator).
 		Times(1).
 		Return(testOnDiskContainerImagePath, nil)
 

diff --git a/...e_build_spec_framework_with_build_file.go → ...ld_spec_framework_with_build_file_test.go b/...e_build_spec_framework_with_build_file.go → ...ld_spec_framework_with_build_file_test.go
@@ -20,10 +20,10 @@ func (suite *KurtosisTypeConstructorTestSuite) TestImageBuildSpecTestWithBuildFi
 	suite.packageContentProvider.EXPECT().
 		GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testBuildContextDir, testNoPackageReplaceOptions).
 		Times(1).
-		Return(testBuildContextLocator, nil)
+		Return(testModulePackageAbsoluteLocator, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePackageFilePath(testContainerImageLocatorWithBuildFile).
+		GetOnDiskAbsolutePackageFilePath(testContainerImageAbsoluteLocatorWithBuildFile).
 		Times(1).
 		Return(testOnDiskContainerImagePathWithBuildFile, nil)
 
@@ -56,5 +56,4 @@ func (t *imageBuildSpecWithBuildFileTest) Assert(typeValue builtin_argument.Kurt
 	require.Nil(t, err)
 	require.Equal(t, testOnDiskContainerImagePathWithBuildFile, imageBuildSpec.GetContainerImageFilePath())
 	require.Equal(t, testOnDiskContextDirPath, imageBuildSpec.GetBuildContextDir())
-	//require.Equal(t, "", imageBuildSpec.GetTargetStage())
 }
diff --git a/...tosis_starlark_framework/test_engine/image_build_spec_framework_with_target_stage_test.go b/...tosis_starlark_framework/test_engine/image_build_spec_framework_with_target_stage_test.go
@@ -20,10 +20,10 @@ func (suite *KurtosisTypeConstructorTestSuite) TestImageBuildSpecWithTargetStage
 	suite.packageContentProvider.EXPECT().
 		GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testBuildContextDir, testNoPackageReplaceOptions).
 		Times(1).
-		Return(testBuildContextLocator, nil)
+		Return(testModulePackageAbsoluteLocator, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePackageFilePath(testContainerImageLocator).
+		GetOnDiskAbsolutePackageFilePath(testContainerImageAbsoluteLocator).
 		Times(1).
 		Return(testOnDiskContainerImagePath, nil)
 

diff --git a/.../startosis_engine/kurtosis_starlark_framework/test_engine/import_module_framework_test.go b/.../startosis_engine/kurtosis_starlark_framework/test_engine/import_module_framework_test.go
@@ -38,8 +38,8 @@ func (suite *KurtosisHelperTestSuite) TestImportFile() {
 	// start with an empty cache to validate it gets populated
 	moduleGlobalCache := map[string]*startosis_packages.ModuleCacheEntry{}
 
-	suite.packageContentProvider.EXPECT().GetModuleContents(testModuleFileName).Return("Hello World!", nil)
-	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, startosis_constants.PackageIdPlaceholderForStandaloneScript, testModuleRelativeLocator, testNoPackageReplaceOptions).Return(testModuleFileName, nil)
+	suite.packageContentProvider.EXPECT().GetModuleContents(testModuleAbsoluteLocator).Return("Hello World!", nil)
+	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, startosis_constants.PackageIdPlaceholderForStandaloneScript, testModuleRelativeLocator, testNoPackageReplaceOptions).Return(testModuleAbsoluteLocator, nil)
 
 	suite.run(&importModuleTestCase{
 		T:                      suite.T(),

diff --git a/...tarlark_framework/test_engine/import_module_with_local_absolute_locator_framework_test.go b/...tarlark_framework/test_engine/import_module_with_local_absolute_locator_framework_test.go
@@ -33,7 +33,7 @@ type importModuleWithLocalAbsoluteLocatorTestCase struct {
 }
 
 func (suite *KurtosisHelperTestSuite) TestImportFileWithLocalAbsoluteLocatorShouldNotBeValid() {
-	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testModuleFileName, testNoPackageReplaceOptions).Return("", startosis_errors.NewInterpretationError(importModuleWithLocalAbsoluteLocatorExpectedErrorMsg))
+	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testModuleFileName, testNoPackageReplaceOptions).Return(emptyAbsoluteLocator, startosis_errors.NewInterpretationError(importModuleWithLocalAbsoluteLocatorExpectedErrorMsg))
 
 	// start with an empty cache to validate it gets populated
 	moduleGlobalCache := map[string]*startosis_packages.ModuleCacheEntry{}

diff --git a/...startosis_engine/kurtosis_starlark_framework/test_engine/nix_build_spec_framework_test.go b/...startosis_engine/kurtosis_starlark_framework/test_engine/nix_build_spec_framework_test.go
@@ -20,15 +20,15 @@ func (suite *KurtosisTypeConstructorTestSuite) TestNixBuildSpecTest() {
 	suite.packageContentProvider.EXPECT().
 		GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testBuildContextDir, testNoPackageReplaceOptions).
 		Times(1).
-		Return(testBuildContextLocator, nil)
+		Return(testModulePackageAbsoluteLocator, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePackageFilePath(testNixFlakeLocator).
+		GetOnDiskAbsolutePackageFilePath(testNixFlakeAbsoluteLocator).
 		Times(1).
 		Return(testOnDiskNixFlakePath, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePath(testBuildContextLocator).
+		GetOnDiskAbsolutePath(testBuildContextAbsoluteLocator).
 		Times(1).
 		Return(testOnDiskContextDirPath, nil)
 

diff --git a/...rver/startosis_engine/kurtosis_starlark_framework/test_engine/read_file_framework_test.go b/...rver/startosis_engine/kurtosis_starlark_framework/test_engine/read_file_framework_test.go
@@ -18,8 +18,8 @@ type readFileTestCase struct {
 }
 
 func (suite *KurtosisHelperTestSuite) TestReadFile() {
-	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, startosis_constants.PackageIdPlaceholderForStandaloneScript, testModuleRelativeLocator, testNoPackageReplaceOptions).Return(testModuleFileName, nil)
-	suite.packageContentProvider.EXPECT().GetModuleContents(testModuleFileName).Return("Hello World!", nil)
+	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, startosis_constants.PackageIdPlaceholderForStandaloneScript, testModuleRelativeLocator, testNoPackageReplaceOptions).Return(testModuleAbsoluteLocator, nil)
+	suite.packageContentProvider.EXPECT().GetModuleContents(testModuleAbsoluteLocator).Return("Hello World!", nil)
 
 	suite.run(&readFileTestCase{
 		T:                      suite.T(),
@@ -41,6 +41,6 @@ func (t *readFileTestCase) GetStarlarkCodeForAssertion() string {
 
 func (t *readFileTestCase) Assert(result starlark.Value) {
 	t.packageContentProvider.AssertCalled(t, "GetAbsoluteLocator", testModulePackageId, startosis_constants.PackageIdPlaceholderForStandaloneScript, testModuleRelativeLocator, testNoPackageReplaceOptions)
-	t.packageContentProvider.AssertCalled(t, "GetModuleContents", testModuleFileName)
+	t.packageContentProvider.AssertCalled(t, "GetModuleContents", testModuleAbsoluteLocator)
 	require.Equal(t, result, starlark.String("Hello World!"))
 }
diff --git a/...is_starlark_framework/test_engine/read_file_with_local_absolute_locator_framework_test.go b/...is_starlark_framework/test_engine/read_file_with_local_absolute_locator_framework_test.go
@@ -21,7 +21,7 @@ type readFileWithLocalAbsoluteLocatorTestCase struct {
 }
 
 func (suite *KurtosisHelperTestSuite) TestReadFileWithLocalAbsoluteLocatorShouldNotBeValid() {
-	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testModuleFileName, testNoPackageReplaceOptions).Return("", startosis_errors.NewInterpretationError(readFileWithLocalAbsoluteLocatorExpectedErrorMsg))
+	suite.packageContentProvider.EXPECT().GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testModuleFileName, testNoPackageReplaceOptions).Return(emptyAbsoluteLocator, startosis_errors.NewInterpretationError(readFileWithLocalAbsoluteLocatorExpectedErrorMsg))
 
 	suite.runShouldFail(
 		testModuleMainFileLocator,

diff --git a/...is_engine/kurtosis_starlark_framework/test_engine/service_config_image_build_spec_test.go b/...is_engine/kurtosis_starlark_framework/test_engine/service_config_image_build_spec_test.go
@@ -25,10 +25,10 @@ func (suite *KurtosisTypeConstructorTestSuite) TestServiceConfigWithImageBuildSp
 	suite.packageContentProvider.EXPECT().
 		GetAbsoluteLocator(testModulePackageId, testModuleMainFileLocator, testBuildContextDir, testNoPackageReplaceOptions).
 		Times(1).
-		Return(testBuildContextLocator, nil)
+		Return(testModulePackageAbsoluteLocator, nil)
 
 	suite.packageContentProvider.EXPECT().
-		GetOnDiskAbsolutePackageFilePath(testContainerImageLocator).
+		GetOnDiskAbsolutePackageFilePath(testContainerImageAbsoluteLocator).
 		Times(1).
 		Return(testOnDiskContainerImagePath, nil)
 

diff --git a/...ainer/server/startosis_engine/kurtosis_starlark_framework/test_engine/static_constants.go b/...ainer/server/startosis_engine/kurtosis_starlark_framework/test_engine/static_constants.go
@@ -4,6 +4,7 @@ import (
 	"github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_interface/objects/enclave"
 	"github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_interface/objects/port_spec"
 	"github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_interface/objects/service"
+	"github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/startosis_packages"
 	"github.com/kurtosis-tech/kurtosis/core/server/commons/enclave_data_directory"
 )
 
@@ -21,25 +22,30 @@ var (
 
 	testSrcPath = "/path/to/file.txt"
 
-	testModulePackageId       = "github.com/kurtosistech/test-package"
-	testModuleMainFileLocator = "github.com/kurtosistech/test-package/main.star"
-	testModuleFileName        = "github.com/kurtosistech/test-package/helpers.star"
-	testModuleRelativeLocator = "./helpers.star"
-
-	testContainerImageName                    = "kurtosistech/example-datastore-server"
-	testBuildContextDir                       = "./"
-	testBuildFile                             = "foo.Dockerfile"
-	testTargetStage                           = "builder"
-	testBuildArgName1                         = "BUILD_ARG_1"
-	testBuildArgValue1                        = "VALUE_1"
-	testBuildArgName2                         = "BUILD_ARG_2"
-	testBuildArgValue2                        = "VALUE_2"
-	testBuildContextLocator                   = testModulePackageId
-	testContainerImageLocator                 = "github.com/kurtosistech/test-package/Dockerfile"
-	testContainerImageLocatorWithBuildFile    = "github.com/kurtosistech/test-package/foo.Dockerfile"
-	testOnDiskContextDirPath                  = "kurtosis-data/test-package"
-	testOnDiskContainerImagePath              = "kurtosis-data/test-package/Dockerfile"
-	testOnDiskContainerImagePathWithBuildFile = "kurtosis-data/test-package/foo.Dockerfile"
+	testModulePackageId              = "github.com/kurtosistech/test-package"
+	testModulePackageAbsoluteLocator = startosis_packages.NewPackageAbsoluteLocator(testModulePackageId, "")
+	testModuleMainFileLocator        = "github.com/kurtosistech/test-package/main.star"
+	testModuleFileName               = "github.com/kurtosistech/test-package/helpers.star"
+	testModuleRelativeLocator        = "./helpers.star"
+
+	testModuleAbsoluteLocator = startosis_packages.NewPackageAbsoluteLocator(testModuleFileName, "")
+
+	emptyAbsoluteLocator = startosis_packages.NewPackageAbsoluteLocator("", "")
+
+	testContainerImageName                         = "kurtosistech/example-datastore-server"
+	testBuildContextDir                            = "./"
+	testBuildFile                                  = "foo.Dockerfile"
+	testTargetStage                                = "builder"
+	testBuildArgName1                              = "BUILD_ARG_1"
+	testBuildArgValue1                             = "VALUE_1"
+	testBuildArgName2                              = "BUILD_ARG_2"
+	testBuildArgValue2                             = "VALUE_2"
+	testBuildContextAbsoluteLocator                = startosis_packages.NewPackageAbsoluteLocator(testModulePackageId, "")
+	testContainerImageAbsoluteLocator              = startosis_packages.NewPackageAbsoluteLocator("github.com/kurtosistech/test-package/Dockerfile", "")
+	testContainerImageAbsoluteLocatorWithBuildFile = startosis_packages.NewPackageAbsoluteLocator("github.com/kurtosistech/test-package/foo.Dockerfile", "")
+	testOnDiskContextDirPath                       = "kurtosis-data/test-package"
+	testOnDiskContainerImagePath                   = "kurtosis-data/test-package/Dockerfile"
+	testOnDiskContainerImagePathWithBuildFile      = "kurtosis-data/test-package/foo.Dockerfile"
 
 	testNixContextDir           = "./"
 	testNixImageName            = "test-image"
@@ -48,7 +54,7 @@ var (
 	testOnDiskNixContextDirPath = "kurtosis-data/test-package"
 	testOnDiskNixFlakePath      = "kurtosis-data/test-package/server/app/flake.nix"
 	testOnDiskNixFlakeDir       = "kurtosis-data/test-package/server/app"
-	testNixFlakeLocator         = "github.com/kurtosistech/test-package/server/app/flake.nix"
+	testNixFlakeAbsoluteLocator = startosis_packages.NewPackageAbsoluteLocator("github.com/kurtosistech/test-package/server/app/flake.nix", "")
 
 	testRegistryAddr     = "http://registry.test.io"
 	testRegistryUsername = "kurtosis"

diff --git a/...r/api_container/server/startosis_engine/kurtosis_types/service_config/image_build_spec.go b/...r/api_container/server/startosis_engine/kurtosis_types/service_config/image_build_spec.go
@@ -232,11 +232,13 @@ func getOnDiskImageBuildSpecPaths(
 	}
 
 	// get on disk directory path of Dockerfile
-	containerImageAbsoluteLocator := path.Join(contextDirAbsoluteLocator, defaultContainerImageFileName)
+	containerImageAbsoluteLocatorStr := path.Join(contextDirAbsoluteLocator.GetLocator(), defaultContainerImageFileName)
 	if buildFile != "" {
-		containerImageAbsoluteLocator = path.Join(contextDirAbsoluteLocator, buildFile)
+		containerImageAbsoluteLocatorStr = path.Join(contextDirAbsoluteLocator.GetLocator(), buildFile)
 	}
 
+	containerImageAbsoluteLocator := startosis_packages.NewPackageAbsoluteLocator(containerImageAbsoluteLocatorStr, contextDirAbsoluteLocator.GetTagBranchOrCommit())
+
 	containerImagePathOnDisk, interpretationErr := packageContentProvider.GetOnDiskAbsolutePackageFilePath(containerImageAbsoluteLocator)
 	if interpretationErr != nil {
 		return "", "", interpretationErr

diff --git a/...ver/api_container/server/startosis_engine/kurtosis_types/service_config/nix_build_spec.go b/...ver/api_container/server/startosis_engine/kurtosis_types/service_config/nix_build_spec.go
@@ -214,7 +214,9 @@ func getOnDiskNixBuildSpecPaths(
 	}
 
 	// get on disk directory path of Dockerfile
-	flakeNixAbsoluteLocator := path.Join(contextDirAbsoluteLocator, flakeLocationDir, defaultNixFlakeFile)
+	flakeNixAbsoluteLocatorStr := path.Join(contextDirAbsoluteLocator.GetLocator(), flakeLocationDir, defaultNixFlakeFile)
+
+	flakeNixAbsoluteLocator := startosis_packages.NewPackageAbsoluteLocator(flakeNixAbsoluteLocatorStr, contextDirAbsoluteLocator.GetTagBranchOrCommit())
 
 	flakeNixPathOnDisk, interpretationErr := packageContentProvider.GetOnDiskAbsolutePackageFilePath(flakeNixAbsoluteLocator)
 	if interpretationErr != nil {

diff --git a/core/server/api_container/server/startosis_engine/startosis_packages/absolute_locator.go b/core/server/api_container/server/startosis_engine/startosis_packages/absolute_locator.go
@@ -0,0 +1,35 @@
+package startosis_packages
+
+import "fmt"
+
+const (
+	defaultMainBranch = ""
+)
+
+// PackageAbsoluteLocator represents the absolute locator for a file in a Kurtosis package
+type PackageAbsoluteLocator struct {
+	// it is the file locator value
+	locator string
+	// indicates if the absolute locator correspond to a specific tag, branch or commit
+	// the zero value (empty string) correspond to the main (or master) branch
+	tagBranchOrCommit string
+}
+
+func NewPackageAbsoluteLocator(locator string, tagBranchOrCommit string) *PackageAbsoluteLocator {
+	return &PackageAbsoluteLocator{locator: locator, tagBranchOrCommit: tagBranchOrCommit}
+}
+
+func (packageAbsoluteLocator *PackageAbsoluteLocator) GetLocator() string {
+	return packageAbsoluteLocator.locator
+}
+
+func (packageAbsoluteLocator *PackageAbsoluteLocator) GetTagBranchOrCommit() string {
+	return packageAbsoluteLocator.tagBranchOrCommit
+}
+
+func (packageAbsoluteLocator *PackageAbsoluteLocator) GetGitURL() string {
+	if packageAbsoluteLocator.tagBranchOrCommit == defaultMainBranch {
+		return packageAbsoluteLocator.locator
+	}
+	return fmt.Sprintf("%s@%s", packageAbsoluteLocator.locator, packageAbsoluteLocator.tagBranchOrCommit)
+}