feat(build, stapel): add disableGitAfterPatch directive

Signed-off-by: Aleksei Igrychev <aleksei.igrychev@palark.com>

Author: alexey-igrychev

docs/_data/werf_yaml.yml

@@ -342,6 +342,14 @@ sections:
           ru: "Версия кеша"
         detailsArticle:
           all: "/usage/build/stapel/base.html#fromcacheversion"
+      - name: disableGitAfterPatch
+        value: "bool"
+        description:
+          en: "Disable updating git sources (gitCache, gitLatestPatch stages)"
+          ru: "Отключение актуализации исходников Git (стадии gitCache, gitLatestPatch)"
+        detailsArticle:
+          en: "/usage/build/stapel/instructions.html#disabling-source-updates-skipping-gitcache-and-gitlatestpatch-stages"
+          ru: "/usage/build/stapel/instructions.html#отключение-обновления-исходников-стадии-gitcache-и-gitlatestpatch"
       - name: git
         description:
           en: "Set of directives to add source files from git repositories (both the project repository and any other)"

docs/pages_en/usage/build/stapel/instructions.md

@@ -504,6 +504,16 @@ shell:
 
 The _git mapping configuration_ in the above `werf.yaml` instructs werf to transfer the contents of the `/src` directory of the local Git repository to the `/app` directory of the image. During the first build, files will be cached at the _gitArchive_ stage, and assembly instructions for _install_ and _beforeSetup_ will be executed. During the builds triggered by the subsequent commits which leave the contents of the `/src` directory unchanged, werf will not run the assembly instructions. Changes in the `/src` directory due to some commit will also result in changes in the checksums of the files matching the mask. This will cause werf to apply the git patch and rebuild any existing stages starting with _beforeSetup_, namely _beforeSetup_ and _setup_. The git patch will be applied once during the _beforeSetup_ stage.
 
+### Disabling source updates (skipping gitCache and gitLatestPatch stages)
+
+The `disableGitAfterPatch` directive allows you to lock the source code in the image during the artifact build stage and prevent it from being updated in subsequent builds.
+
+This approach is useful in scenarios where you need to use the actual set of source files during the build stage, but only changes to specific files should restart the build process.
+
+Therefore:
+- If `git.stageDependencies` is used, the rebuild, and execution of commands with the current source files, will occur when relevant changes are detected.
+- If `git.stageDependencies` is not used, there will be no rebuilds.
+
 ## Dependency on the CacheVersion
 
 There are situations when a user wants to rebuild all _user stages_ or just one of them. They can do so by changing `cacheVersion` or `<user stage name>CacheVersion` parameters.

docs/pages_ru/usage/build/stapel/instructions.md

@@ -533,6 +533,16 @@ shell:
 
 Сборка следующего коммита, в котором будут только изменения файлов за пределами каталога `/src`, не приведет к выполнению инструкций каких-либо стадий. Если коммит будет содержать изменение внутри каталога `/src`, контрольные суммы файлов подпадающих под маску изменятся, werf применит Git-патч и пересоберёт все пользовательские стадии, начиная со стадии _beforeSetup_, а именно — _beforeSetup_ и _setup_. Применение Git-патча будет выполнено один раз на стадии _beforeSetup_.
 
+### Отключение обновления исходников (стадии gitCache и gitLatestPatch)
+
+Параметр `disableGitAfterPatch` позволяет зафиксировать исходный код в образе на этапе сборки артефакта и предотвратить его обновление при последующих сборках. 
+
+Этот подход полезен в случаях, когда необходимо использовать актуальный набор исходных файлов на этапе сборки, но изменения только определенных файлов должны перезапускать процесс сборки. 
+
+Таким образом:
+- если использовать `git.stageDepedencies`, то пересборка, выполнение команд с актуальными исходниками, будет выполняться при соответствующих изменениях;
+- если не использовать `git.stageDepedencies`, то пересборок не будет.
+
 ## Зависимость от значения CacheVersion
 
 Существуют ситуации, когда необходимо принудительно пересобрать все или какую-то конкретную _пользовательскую стадию_. Этого можно достичь, изменяя параметры `cacheVersion` или `<user stage name>CacheVersion`.

pkg/build/image/stapel.go

@@ -107,7 +107,7 @@ func initStages(ctx context.Context, image *Image, metaConfig *config.Meta, stap
 	stages = appendIfExist(ctx, stages, stage.GenerateSetupStage(ctx, imageBaseConfig, gitPatchStageOptions, baseStageOptions))
 	stages = appendIfExist(ctx, stages, stage.GenerateDependenciesAfterSetupStage(imageBaseConfig, baseStageOptions))
 
-	if !stapelImageConfig.IsArtifact() {
+	if !stapelImageConfig.IsGitAfterPatchDisabled() {
 		if gitMappingsExist {
 			stages = append(stages, stage.NewGitCacheStage(gitPatchStageOptions, baseStageOptions))
 			stages = append(stages, stage.NewGitLatestPatchStage(gitPatchStageOptions, baseStageOptions))

pkg/config/git_manager.go

@@ -3,4 +3,6 @@ package config
 type GitManager struct {
 	Local  []*GitLocal
 	Remote []*GitRemote
+
+	isGitAfterPatchDisabled bool
 }

pkg/config/raw_stapel_image.go

@@ -7,22 +7,23 @@ import (
 )
 
 type rawStapelImage struct {
-	Images           []string         `yaml:"-"`
-	Final            *bool            `yaml:"final,omitempty"`
-	Artifact         string           `yaml:"artifact,omitempty"`
-	From             string           `yaml:"from,omitempty"`
-	FromLatest       bool             `yaml:"fromLatest,omitempty"`
-	FromCacheVersion string           `yaml:"fromCacheVersion,omitempty"`
-	FromImage        string           `yaml:"fromImage,omitempty"`
-	FromArtifact     string           `yaml:"fromArtifact,omitempty"`
-	RawGit           []*rawGit        `yaml:"git,omitempty"`
-	RawShell         *rawShell        `yaml:"shell,omitempty"`
-	RawAnsible       *rawAnsible      `yaml:"ansible,omitempty"`
-	RawMount         []*rawMount      `yaml:"mount,omitempty"`
-	RawDocker        *rawDocker       `yaml:"docker,omitempty"`
-	RawImport        []*rawImport     `yaml:"import,omitempty"`
-	RawDependencies  []*rawDependency `yaml:"dependencies,omitempty"`
-	Platform         []string         `yaml:"platform,omitempty"`
+	Images               []string         `yaml:"-"`
+	Final                *bool            `yaml:"final,omitempty"`
+	Artifact             string           `yaml:"artifact,omitempty"`
+	From                 string           `yaml:"from,omitempty"`
+	FromLatest           bool             `yaml:"fromLatest,omitempty"`
+	FromCacheVersion     string           `yaml:"fromCacheVersion,omitempty"`
+	FromImage            string           `yaml:"fromImage,omitempty"`
+	FromArtifact         string           `yaml:"fromArtifact,omitempty"`
+	DisableGitAfterPatch bool             `yaml:"disableGitAfterPatch,omitempty"`
+	RawGit               []*rawGit        `yaml:"git,omitempty"`
+	RawShell             *rawShell        `yaml:"shell,omitempty"`
+	RawAnsible           *rawAnsible      `yaml:"ansible,omitempty"`
+	RawMount             []*rawMount      `yaml:"mount,omitempty"`
+	RawDocker            *rawDocker       `yaml:"docker,omitempty"`
+	RawImport            []*rawImport     `yaml:"import,omitempty"`
+	RawDependencies      []*rawDependency `yaml:"dependencies,omitempty"`
+	Platform             []string         `yaml:"platform,omitempty"`
 
 	doc *doc `yaml:"-"` // parent
 
@@ -121,6 +122,10 @@ func (c *rawStapelImage) toStapelImageArtifactDirectives(giterminismManager gite
 	}
 	imageArtifact.StapelImageBase.final = false
 
+	if imageArtifact.Git != nil {
+		imageArtifact.Git.isGitAfterPatchDisabled = true
+	}
+
 	if err := c.validateStapelImageArtifactDirective(imageArtifact); err != nil {
 		return nil, err
 	}
@@ -210,6 +215,8 @@ func (c *rawStapelImage) validateStapelImageArtifactDirective(imageArtifact *Sta
 		return newDetailedConfigError("`docker` section is not supported for artifact!", nil, c.doc)
 	} else if c.Final != nil {
 		return newDetailedConfigError("`final` directive is not supported for artifact!", nil, c.doc)
+	} else if c.DisableGitAfterPatch {
+		return newDetailedConfigError("`disableGitAfterPatch` directive is not supported for artifact!", nil, c.doc)
 	}
 
 	if err := imageArtifact.validate(); err != nil {
@@ -316,6 +323,7 @@ func (c *rawStapelImage) toBaseStapelImageBaseDirective(giterminismManager giter
 	}
 
 	imageBase.Git = &GitManager{}
+	imageBase.Git.isGitAfterPatchDisabled = c.DisableGitAfterPatch
 
 	imageBase.raw = c
 

pkg/config/stapel_image_base.go

@@ -40,8 +40,12 @@ func (c *StapelImageBase) ImageBaseConfig() *StapelImageBase {
 	return c
 }
 
-func (c *StapelImageBase) IsArtifact() bool {
-	return false
+func (c *StapelImageBase) IsGitAfterPatchDisabled() bool {
+	if c.Git == nil {
+		return false
+	}
+
+	return c.Git.isGitAfterPatchDisabled
 }
 
 func (c *StapelImageBase) IsFinal() bool {

pkg/config/stapel_image_interface.go

@@ -3,5 +3,5 @@ package config
 type StapelImageInterface interface {
 	ImageInterface
 	ImageBaseConfig() *StapelImageBase
-	IsArtifact() bool
+	IsGitAfterPatchDisabled() bool
 }