Merge pull request #455 from buildkite-plugins/toote_prebuild_clarifications

Pre-build image clarifications

Author: pzeballos

README.md

@@ -32,7 +32,9 @@ The name of the service the command should be run within. If the docker-compose
 
 A list of services to push.  You can specify just the service name to push or the format `service:registry:tag` to override where the service's image is pushed to. Needless to say, the image for the service must have been built in the very same step or built and pushed previously to ensure it is available for pushing.
 
-:warning: The `push` command will fail if a `login` command has not previously been used or the agent has not been authenticated for an image registry.
+:warning: If a service does not have an `image` configuration and no registry/tag are specified in the `push` option, pushing of the service will be skipped by docker.
+
+:warning: The `push` command will fail when the image refers to a remote registry that requires a login and the agent has not been authenticated for it (for example, using the [ecr](https://github.com/buildkite-plugins/ecr-buildkite-plugin) or [docker-login](https://github.com/buildkite-plugins/docker-login-buildkite-plugin) plugins).
 
 ### Other options
 
@@ -294,6 +296,12 @@ Note that [the effect of this option changes depending on your docker compose CL
 
 Sets the `--entrypoint` argument when running `docker compose`.
 
+#### `require-prebuild` (run only, boolean)
+
+If no prebuilt image is found for the run step, it will cause the plugin to fail the step.
+
+The default is `false`.
+
 #### `service-ports` (run only, boolean)
 
 If set to true, docker compose will run with the service ports enabled and mapped to the host. Equivalent to `--service-ports` in docker-compose.

docs/examples.md

@@ -194,9 +194,12 @@ steps:
     plugins:
       - docker-compose#v5.3.0:
           run: app
+          require-prebuild: true
 ```
 
-All `run` steps for the service `app` will automatically pull and use the pre-built image. Without this, each `Test %n` job would build its own instead.
+All `run` steps for the service `app` will automatically pull and use the pre-built image. Note that, for the example to work as-is, the `app` service needs to have an `image` element defined or the build/push step needs to be changed to `push: app:the_registry:the_tag` (and the agent running all the steps need to be authenticated against the registry if required).
+
+Note that the `require-prebuild` option means that if no prebuilt image is found, all `Test %n` jobs will fail. Without it, if the agent the `Test %n` is running on has ever built such an image and has it appropriately tagged it may still run.
 
 ### Building multiple images
 

plugin.yml

@@ -93,6 +93,8 @@ configuration:
       type: integer
     quiet-pull:
       type: boolean
+    require-prebuild:
+      type: boolean
     rm:
       type: boolean
     run-image:
@@ -168,6 +170,7 @@ configuration:
     pull-retries: [ run ]
     push-retries: [ push ]
     quiet-pull: [ run ]
+    require-prebuild: [ run ]
     rm: [ run ]
     run-image: [ run ]
     run-labels: [ run ]

tests/run.bats

@@ -43,6 +43,22 @@ teardown() {
   unstub buildkite-agent
 }
 
+@test "Fail running without a prebuilt image and require-prebuild" {
+  export BUILDKITE_PLUGIN_DOCKER_COMPOSE_RUN=myservice
+  export BUILDKITE_COMMAND="echo hello world"
+  export BUILDKITE_PLUGIN_DOCKER_COMPOSE_REQUIRE_PREBUILD=true
+
+  stub buildkite-agent \
+    "meta-data exists docker-compose-plugin-built-image-tag-myservice : exit 1"
+
+  run "$PWD"/hooks/command
+
+  assert_failure
+  assert_output --partial "No pre-built image found"
+
+  unstub buildkite-agent
+}
+
 @test "Run without a prebuilt image and an empty command" {
   export BUILDKITE_PLUGIN_DOCKER_COMPOSE_RUN=myservice
   export BUILDKITE_COMMAND=""