Add builder.use-once parameter

When `builder.use` is `true`, this plugin calls `docker buildx use` which sets the default builder for the entire Buildkite agent.

This can cause issues for other Buildkite steps on the same agent. For example, another pipeline step might land on the same agent and expect to use the default `docker` driver, which does not require the user to specify `--load` when calling `docker build`. This results in the image not being available for subsequent commands (e.g. `docker tag` or `docker push`) and can break a pipeline that was previously working.

This change adds the `builder.use-once` parameter. When `true`, the plugin will pass the `--builder` flag to `docker build` instead of calling `docker buildx use`. This ensures that the specified builder is only used for this particular step.

Author: KevinSnyderCodes

commands/build.sh

@@ -111,6 +111,10 @@ fi
 
 build_params+=(build)
 
+if [[ -n "$(plugin_read_config BUILDER_NAME "")" ]] && [[ "$(plugin_read_config BUILDER_USE_ONCE "false")" == "true" ]]; then
+  build_params+=("--builder" "$(plugin_read_config BUILDER_NAME "")")
+fi
+
 if [[ ! "$(plugin_read_config SKIP_PULL "false")" == "true" ]] ; then
   build_params+=(--pull)
 fi

hooks/pre-command

@@ -8,11 +8,12 @@ DIR="$(cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd)"
 
 builder_create="$(plugin_read_config BUILDER_CREATE "false")"
 builder_use="$(plugin_read_config BUILDER_USE "false")"
+builder_use_once="$(plugin_read_config BUILDER_USE_ONCE "false")"
 builder_name="$(plugin_read_config BUILDER_NAME "")"
 
-if [[ "${builder_create}" == "true" ]] || [[ "${builder_use}" == "true" ]]; then
+if [[ "${builder_create}" == "true" ]] || [[ "${builder_use}" == "true" ]] || [[ "${builder_use_once}" == "true" ]]; then
     if [[ -z "${builder_name}" ]]; then
-        echo "+++ 🚨 Builder Name cannot be empty when using 'create' or 'use' parameters"
+        echo "+++ 🚨 Builder Name cannot be empty when using 'create', 'use', or 'use-once' parameters"
         exit 1
     fi
 fi
@@ -62,8 +63,8 @@ if [[ "${builder_create}" == "true" ]]; then
 
         echo "~~~ :docker: Creating Builder Instance '${builder_name}' with Driver '${build_driver}'"
         docker buildx create "${builder_instance_args[@]}"
-        if [[ "${builder_use}" == "false" ]]; then
-            echo "~~~ :warning: Builder Instance '${builder_name}' created but will not be used as 'use: true' parameter not specified"
+        if [[ "${builder_use}" == "false" ]] && [[ "${builder_use_once}" == "false" ]]; then
+            echo "~~~ :warning: Builder Instance '${builder_name}' created but will not be used as 'use: true' or 'use-once: true' parameter not specified"
         fi
     else
         echo "~~~ :docker: Not Creating Builder Instance '${builder_name}' as already exists"
@@ -78,8 +79,10 @@ if [[ "${builder_use}" == "true" ]]; then
         echo "+++ 🚨 Builder Instance '${builder_name}' does not exist"
         exit 1
     fi
-else
+elif [[ "${builder_use_once}" == "false" ]]; then
     current_builder=$(docker buildx inspect | grep -m 1 "Name" | awk '{print $2}') || true
     current_builder_driver=$(docker buildx inspect | grep -m 1 "Driver" | awk '{print $2}') || true
     echo "~~~ :docker: Using Default Builder '${current_builder}' with Driver '${current_builder_driver}'"
+else
+    echo "~~~ :docker: Using Builder Instance '${builder_name}' once"
 fi

tests/builder-instances.bats

@@ -25,7 +25,7 @@ load '../lib/shared'
     run "$PWD"/hooks/pre-command
 
     assert_failure
-    assert_output "+++ 🚨 Builder Name cannot be empty when using 'create' or 'use' parameters"
+    assert_output "+++ 🚨 Builder Name cannot be empty when using 'create', 'use', or 'use-once' parameters"
 }
 
 @test "Use Builder Instance with invalid Name" {
@@ -34,7 +34,7 @@ load '../lib/shared'
     run "$PWD"/hooks/pre-command
 
     assert_failure
-    assert_output "+++ 🚨 Builder Name cannot be empty when using 'create' or 'use' parameters"
+    assert_output "+++ 🚨 Builder Name cannot be empty when using 'create', 'use', or 'use-once' parameters"
 }
 
 @test "Create Builder Instance with invalid Driver" {
@@ -104,8 +104,8 @@ load '../lib/shared'
 
     assert_success
     assert_output --partial "~~~ :docker: Creating Builder Instance 'builder-name' with Driver 'docker-container'"
-    assert_output --partial "~~~ :warning: Builder Instance 'builder-name' created but will not be used as 'use: true' parameter not specified"
-    
+    assert_output --partial "~~~ :warning: Builder Instance 'builder-name' created but will not be used as 'use: true' or 'use-once: true' parameter not specified"
+
     assert_output --partial "~~~ :docker: Using Default Builder 'test' with Driver 'driver'"
 
     unstub docker
@@ -198,7 +198,7 @@ load '../lib/shared'
 
     assert_success
     assert_output "~~~ :docker: Cleaning up Builder Instance 'builder-name'"
-    
+
     unstub docker
 }