Add builder.output configuration for buildx output parameters

[sjparkinson]

This change adds a new configration option, that allows you to pass buildx build output parameters¹.

I can see this mainly being used to configure compression.

For a bit of context, I found #1549 when trying to sort this out myself today.

Using zstd should(?) be a bit faster to deploy that the default gzip, compression level 3 is the default level. I'm using the patch from the discussion on a Ubuntu Hetzner VM with no issues. Useful when deploying locally on a slow upstream connection with a local registry.

Configuration would look like:

builder:
  arch: amd64
  output: compression=zstd,force-compression=true

Worth noting, kamal build push already supports an --output option, so you could achieve this today as a two command deploy:

bin/kamal build push --output registry,compression=zstd
bin/kamal deploy --skip-push

Footnotes

1. https://docs.docker.com/build/exporters/image-registry/#synopsis ↩

[Copilot]

Pull request overview

This PR introduces a new builder.output configuration option to let users append Docker buildx output type parameters (e.g., compression settings) to the docker buildx build --output=... invocation used during image pushes.

Changes:

• Add builder.output to configuration and expose it via Kamal::Configuration::Builder.
• Append configured output parameters to the buildx --output flag during builder.push.
• Document the new setting and add configuration/command coverage in tests.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/configuration/builder_test.rb	Adds tests for default and configured builder.output.
test/commands/builder_test.rb	Ensures buildx push command includes appended output parameters.
lib/kamal/configuration/docs/builder.yml	Documents the new builder.output config option (and drives config validation).
lib/kamal/configuration/builder.rb	Adds output accessor to the builder configuration object.
lib/kamal/commands/builder/base.rb	Extends buildx push command to include the configured output parameters.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

output is concatenated directly into the --output=... argument. If the config sets builder.output to an empty string, this produces --output=type=registry, (invalid). Also, because this string is inserted unescaped, shell metacharacters in the config value can alter the command line. Consider using output.presence and shell-escaping/quoting the composed --output value before passing it to the command runner.

[sjparkinson]

output is concatenated directly into the --output=... argument. If the config sets builder.output to an empty string, this produces --output=type=registry, (invalid).

Resolved with 2b90bda, and it was correct:

 DEBUG [ef911763] Command: docker buildx build --output=type=registry,,compression=zstd,compression-level=12,force-compression=true --platform linux/amd64 --builder kamal-local-registry-docker-container -t localhost:5555/sjparkinson/...:21e4d76 -t localhost:5555/sjparkinson/...:latest --label service="..." --file Dockerfile . 2>&1
 DEBUG [ef911763] 	ERROR: invalid value
  ERROR (SSHKit::Command::Failed): docker exit status: 256
docker stdout: ERROR: invalid value
docker stderr: Nothing written

I've left the shell escaping as that is the case for other configuration too, worth tacking on its own imo.