feat: add support for git revision and context dir options to image builds (#933)

Add `repository_revision` and `context_dir` fields to `build_parameters` (session environments built from code).

Details:
* `repository_revision` allows users to specify a git revision (branch, tag or commit) to build from.
* `context_dir` allows users to specify the relative path to a folder to build from
* Both `context_dir` and `repository_revision` can be reset by providing the empty string in the `PATCH` endpoint.

Author: leafty

components/renku_data_services/migrations/versions/9ec3d97e3b3d_update_sessions_build_parameters_table.py

@@ -0,0 +1,32 @@
+"""update sessions.build_parameters table
+
+Revision ID: 9ec3d97e3b3d
+Revises: b402b9d584bf
+Create Date: 2025-07-21 13:33:06.079306
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "9ec3d97e3b3d"
+down_revision = "b402b9d584bf"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "build_parameters", sa.Column("repository_revision", sa.String(length=500), nullable=True), schema="sessions"
+    )
+    op.add_column("build_parameters", sa.Column("context_dir", sa.String(length=500), nullable=True), schema="sessions")
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("build_parameters", "context_dir", schema="sessions")
+    op.drop_column("build_parameters", "repository_revision", schema="sessions")
+    # ### end Alembic commands ###

components/renku_data_services/session/api.spec.yaml

@@ -648,6 +648,24 @@ components:
       type: string
       minLength: 1
       maxLength: 99
+    RepositoryRevision:
+      description: A git revision
+      type: string
+      minLength: 1
+      maxLength: 500
+    RepositoryRevisionPatch:
+      description: A git revision
+      type: string
+      maxLength: 500
+    BuildContextDir:
+      description: The relative path to a folder
+      type: string
+      minLength: 1
+      maxLength: 500
+    BuildContextDirPatch:
+      description: The relative path to a folder
+      type: string
+      maxLength: 500
     EnvironmentIdOnlyPatch:
       type: object
       properties:
@@ -704,6 +722,10 @@ components:
           $ref: "#/components/schemas/BuilderVariant"
         frontend_variant:
           $ref: "#/components/schemas/FrontendVariant"
+        repository_revision:
+          $ref: "#/components/schemas/RepositoryRevision"
+        context_dir:
+          $ref: "#/components/schemas/BuildContextDir"
       required:
         - repository
         - builder_variant
@@ -727,6 +749,10 @@ components:
           $ref: "#/components/schemas/BuilderVariant"
         frontend_variant:
           $ref: "#/components/schemas/FrontendVariant"
+        repository_revision:
+          $ref: "#/components/schemas/RepositoryRevisionPatch"
+        context_dir:
+          $ref: "#/components/schemas/BuildContextDirPatch"
     ContainerImage:
       description: A container image
       type: string

components/renku_data_services/session/apispec.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  api.spec.yaml
-#   timestamp: 2025-04-10T14:23:45+00:00
+#   timestamp: 2025-07-21T13:24:31+00:00
 
 from __future__ import annotations
 
@@ -186,7 +186,7 @@ class EnvironmentWithoutContainerImage(BaseAPISpec):
         min_length=1,
     )
     is_archived: Optional[bool] = Field(
-        None,
+        False,
         description="Whether this environment is archived and not for use in new projects or not",
     )
 
@@ -323,7 +323,7 @@ class EnvironmentPatch(BaseAPISpec):
         min_length=1,
     )
     is_archived: Optional[bool] = Field(
-        None,
+        False,
         description="Whether this environment is archived and not for use in new projects or not",
     )
 
@@ -360,6 +360,12 @@ class BuildParameters(BaseAPISpec):
     frontend_variant: str = Field(
         ..., description="User's Frontend Choice.", max_length=99, min_length=1
     )
+    repository_revision: Optional[str] = Field(
+        None, description="A git revision", max_length=500, min_length=1
+    )
+    context_dir: Optional[str] = Field(
+        None, description="The relative path to a folder", max_length=500, min_length=1
+    )
 
 
 class BuildParametersPost(BuildParameters):
@@ -377,6 +383,12 @@ class BuildParametersPatch(BaseAPISpec):
     frontend_variant: Optional[str] = Field(
         None, description="User's Frontend Choice.", max_length=99, min_length=1
     )
+    repository_revision: Optional[str] = Field(
+        None, description="A git revision", max_length=500
+    )
+    context_dir: Optional[str] = Field(
+        None, description="The relative path to a folder", max_length=500
+    )
 
 
 class BuildCommonPart(BaseAPISpec):

components/renku_data_services/session/core.py

@@ -67,6 +67,8 @@ def validate_unsaved_build_parameters(
         repository=environment.repository,
         builder_variant=environment.builder_variant,
         frontend_variant=environment.frontend_variant,
+        repository_revision=environment.repository_revision,
+        context_dir=environment.context_dir,
     )
 
 
@@ -91,6 +93,8 @@ def validate_build_parameters_patch(environment: apispec.BuildParametersPatch) -
         repository=environment.repository,
         builder_variant=environment.builder_variant,
         frontend_variant=environment.frontend_variant,
+        repository_revision=environment.repository_revision,
+        context_dir=environment.context_dir,
     )
 
 

components/renku_data_services/session/db.py

@@ -141,6 +141,8 @@ def __copy_environment(
                 builder_variant=environment.build_parameters.builder_variant,
                 frontend_variant=environment.build_parameters.frontend_variant,
                 repository=environment.build_parameters.repository,
+                repository_revision=environment.build_parameters.repository_revision,
+                context_dir=environment.build_parameters.context_dir,
             )
             session.add(new_build_parameters)
 
@@ -165,6 +167,8 @@ def __insert_build_parameters_environment(
             builder_variant=new_build_parameters_environment.builder_variant,
             frontend_variant=new_build_parameters_environment.frontend_variant,
             repository=new_build_parameters_environment.repository,
+            repository_revision=new_build_parameters_environment.repository_revision,
+            context_dir=new_build_parameters_environment.context_dir,
         )
         session.add(build_parameters_orm)
 
@@ -262,6 +266,14 @@ async def __update_environment_build_parameters(
             environment.build_parameters.builder_variant = build_parameters.builder_variant
         if build_parameters.frontend_variant is not None:
             environment.build_parameters.frontend_variant = build_parameters.frontend_variant
+        if build_parameters.repository_revision == "":
+            environment.build_parameters.repository_revision = None
+        elif build_parameters.repository_revision:
+            environment.build_parameters.repository_revision = build_parameters.repository_revision
+        if build_parameters.context_dir == "":
+            environment.build_parameters.context_dir = None
+        elif build_parameters.context_dir:
+            environment.build_parameters.context_dir = build_parameters.context_dir
 
     async def update_environment(
         self, user: base_models.APIUser, environment_id: ULID, patch: models.EnvironmentPatch
@@ -406,6 +418,8 @@ async def insert_launcher(
                     builder_variant=launcher.environment.builder_variant,
                     frontend_variant=launcher.environment.frontend_variant,
                     repository=launcher.environment.repository,
+                    repository_revision=launcher.environment.repository_revision,
+                    context_dir=launcher.environment.context_dir,
                 )
                 session.add(build_parameters_orm)
 
@@ -700,6 +714,8 @@ async def __update_launcher_environment(
                     builder_variant=new_custom_built_environment.builder_variant,
                     frontend_variant=new_custom_built_environment.frontend_variant,
                     repository=new_custom_built_environment.repository,
+                    repository_revision=new_custom_built_environment.repository_revision,
+                    context_dir=new_custom_built_environment.context_dir,
                 )
                 session.add(build_parameters_orm)
 
@@ -1024,6 +1040,8 @@ def _get_buildrun_params(
             raise errors.UnauthorizedError(message="You do not have the required permissions for this operation.")
 
         git_repository = build_parameters.repository
+        git_repository_revision = build_parameters.repository_revision
+        context_dir = build_parameters.context_dir
 
         output_image_prefix = (
             self.builds_config.build_output_image_prefix or constants.BUILD_DEFAULT_OUTPUT_IMAGE_PREFIX
@@ -1072,6 +1090,8 @@ def _get_buildrun_params(
             labels=labels,
             annotations=annotations,
             frontend=build_parameters.frontend_variant,
+            git_repository_revision=git_repository_revision,
+            context_dir=context_dir,
         )
 
     async def _get_environment_authorization(

components/renku_data_services/session/k8s_client.py

@@ -183,7 +183,10 @@ async def create_image_build(self, params: models.ShipwrightBuildRunParams, user
             spec=crs.BuildRunSpec(
                 build=crs.Build(
                     spec=crs.BuildSpec(
-                        source=crs.GitSource(git=crs.Git(url=params.git_repository)),
+                        source=crs.GitSource(
+                            git=crs.Git(url=params.git_repository, revision=params.git_repository_revision),
+                            contextDir=params.context_dir,
+                        ),
                         strategy=crs.Strategy(kind="BuildStrategy", name=params.build_strategy_name),
                         paramValues=[
                             crs.ParamValue(name="frontend", value=params.frontend),

components/renku_data_services/session/models.py

@@ -60,6 +60,8 @@ class UnsavedBuildParameters:
     repository: str
     builder_variant: str
     frontend_variant: str
+    repository_revision: str | None = None
+    context_dir: str | None = None
 
 
 @dataclass(kw_only=True, frozen=True, eq=True)
@@ -128,6 +130,8 @@ class BuildParametersPatch:
     repository: str | None = None
     builder_variant: str | None = None
     frontend_variant: str | None = None
+    repository_revision: str | None = None
+    context_dir: str | None = None
 
 
 @dataclass(eq=True, kw_only=True)
@@ -307,6 +311,8 @@ class ShipwrightBuildRunParams:
     annotations: dict[str, str] | None = None
     frontend: str = FrontendVariant.vscodium.value
     build_image: str | None = None
+    git_repository_revision: str | None = None
+    context_dir: str | None = None
 
 
 @dataclass(frozen=True, eq=True, kw_only=True)

components/renku_data_services/session/orm.py

@@ -203,13 +203,21 @@ class BuildParametersORM(BaseORM):
 
     frontend_variant: Mapped[str] = mapped_column("frontend_variant", String(99))
 
+    repository_revision: Mapped[str | None] = mapped_column(
+        "repository_revision", String(500), nullable=True, default=None
+    )
+
+    context_dir: Mapped[str | None] = mapped_column("context_dir", String(500), nullable=True, default=None)
+
     def dump(self) -> models.BuildParameters:
         """Create a session build parameters model from the BuildParametersORM."""
         return models.BuildParameters(
             id=self.id,
             repository=self.repository,
             builder_variant=self.builder_variant,
             frontend_variant=self.frontend_variant,
+            repository_revision=self.repository_revision,
+            context_dir=self.context_dir,
         )