fix(wfctl): add --push flag; fix hardened buildx push/load semantics (#546)

* Initial plan

* fix: add --push flag to wfctl build and fix hardened buildx push/load semantics

Bug 1: Add --push flag to wfctl build as the explicit-push counterpart
to --no-push. --push=false is equivalent to --no-push. This allows
dependent repos to use --push explicitly without a 'flag not defined' error.

Bug 2: In buildWithDockerfile (hardened mode), add --push or --load to
the docker buildx args. The docker-container driver required for
--provenance/--sbom caches the build result in buildkit's cache but does
not export it to the local daemon or registry unless --push or --load is
specified.

- hardened + push: passes --push to buildx (push directly from buildkit)
- hardened + no-push: passes --load to buildx (load into local daemon)

The orchestrator (runBuildOrchestrate) now passes --push to runBuildImage
when hardened mode is active and skips the separate runBuildPush step
(which would fail with 'image does not exist locally' since the hardened
path never loads the image into the docker daemon).

Tests: added TestRunBuildImage_HardenedPushFlag and
TestRunBuildImage_HardenedNoPushAddsLoad to cover both paths.

Fixes: wfctl build --push pipeline broken in hardened mode

Agent-Logs-Url: https://github.com/GoCodeAlone/workflow/sessions/fecb8b30-963c-49ed-b4fb-db5028ae3afb

Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>

* fix: address review feedback on hardened push/load logic

- Only add --push to buildx when push=true AND push_to is non-empty;
  containers without push_to fall back to --load (single-platform) instead.
- Add allImageRefsForContainer helper and use all push_to registries as
  --tag flags for multi-registry hardened pushes in a single buildx call.
- Skip --load for multi-platform + no-push builds (unsupported by buildx);
  leave result in buildkit cache with a comment explaining why.
- Replace fake fset regression test with a real TestRunBuild_PushFlagDefined
  that calls runBuild(["--push", "--dry-run"]) to exercise the real FlagSet.
- Add new tests: HardenedPushNoPushTo, HardenedMultiRegistryPush,
  HardenedMultiPlatformNoPushNoLoad.
- Update docs/manual/build-deploy/05-cli-reference.md: add --push flag to
  wfctl build table, expand wfctl build image synopsis with semantics note.

Agent-Logs-Url: https://github.com/GoCodeAlone/workflow/sessions/eab2c034-93b1-4ef7-aac8-4f62c4744b84

Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>

Author: Copilot

cmd/wfctl/build.go

@@ -57,10 +57,16 @@ func runBuild(args []string) error {
 	fs.StringVar(&tag, "tag", "", "Override image tag for all container targets")
 	fs.StringVar(&format, "format", "table", "Output format: table | json | yaml")
 	fs.BoolVar(&noPush, "no-push", false, "Build but do not push images to registries")
+	var push bool
+	fs.BoolVar(&push, "push", true, "Push images to registries after build (default true; --push=false is equivalent to --no-push)")
 	fs.StringVar(&envName, "env", "", "Environment name for per-env config overrides")
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
+	// --push=false is equivalent to --no-push.
+	if !push {
+		noPush = true
+	}
 
 	if dryRun {
 		os.Setenv("WFCTL_BUILD_DRY_RUN", "1")    //nolint:errcheck
@@ -105,6 +111,11 @@ type buildOpts struct {
 func runBuildOrchestrate(cfg *config.WorkflowConfig, opts buildOpts) error {
 	build := cfg.CI.Build
 
+	// Detect hardened mode once; with buildx (docker-container driver) the push
+	// must be done inside the buildx invocation itself — a separate docker push
+	// would fail because the image is only in buildkit's cache, not the local daemon.
+	hardened := cfg.CI.Build.Security != nil && cfg.CI.Build.Security.Hardened
+
 	// Go targets.
 	for i := range build.Targets {
 		t := &build.Targets[i]
@@ -157,13 +168,21 @@ func runBuildOrchestrate(cfg *config.WorkflowConfig, opts buildOpts) error {
 		if opts.tag != "" {
 			imgArgs = append(imgArgs, "--tag", opts.tag)
 		}
+		// For hardened builds (docker buildx with docker-container driver), pass
+		// --push so buildx pushes directly from the buildkit cache. Without this,
+		// buildx would silently cache the result and the subsequent docker push
+		// would fail with "image does not exist locally".
+		if !opts.noPush && hardened {
+			imgArgs = append(imgArgs, "--push")
+		}
 		if err := runBuildImage(imgArgs); err != nil {
 			return err
 		}
 	}
 
-	// Push step (unless --no-push).
-	if !opts.noPush && !opts.dryRun {
+	// Push step (unless --no-push, dry-run, or hardened mode where buildx
+	// already pushed directly from the buildkit cache).
+	if !opts.noPush && !opts.dryRun && !hardened {
 		pushArgs := []string{}
 		if opts.cfgPath != "" {
 			pushArgs = append(pushArgs, "--config", opts.cfgPath)

cmd/wfctl/build_image.go

@@ -25,6 +25,7 @@ func runBuildImageWithOutput(args []string, out io.Writer) error {
 	cfgPath := fs.String("config", "", "Config file")
 	dryRun := fs.Bool("dry-run", false, "Print planned actions without executing")
 	tagOverride := fs.String("tag", "", "Override image tag for all containers")
+	pushImages := fs.Bool("push", false, "Push images directly via buildx (hardened mode: adds --push to buildx; non-hardened: no effect, separate push step handles it)")
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
@@ -84,15 +85,15 @@ func runBuildImageWithOutput(args []string, out io.Writer) error {
 				return fmt.Errorf("ko build %q: %w", ctr.Name, err)
 			}
 		default: // dockerfile
-			if err := buildWithDockerfile(ctr, tag, *dryRun, hardened, cfg.CI.Registries, out); err != nil {
+			if err := buildWithDockerfile(ctr, tag, *dryRun, hardened, *pushImages, cfg.CI.Registries, out); err != nil {
 				return fmt.Errorf("dockerfile build %q: %w", ctr.Name, err)
 			}
 		}
 	}
 	return nil
 }
 
-func buildWithDockerfile(ctr config.CIContainerTarget, tag string, dryRun bool, hardened bool, registries []config.CIRegistry, out io.Writer) error {
+func buildWithDockerfile(ctr config.CIContainerTarget, tag string, dryRun bool, hardened bool, push bool, registries []config.CIRegistry, out io.Writer) error {
 	dockerfile := ctr.Dockerfile
 	if dockerfile == "" {
 		dockerfile = "Dockerfile"
@@ -154,6 +155,21 @@ func buildWithDockerfile(ctr config.CIContainerTarget, tag string, dryRun bool,
 			fmt.Fprintf(out, "warning: DOCKER_BUILDKIT is not set to 1; provenance attestation requires BuildKit\n")
 		}
 		args = append(args, "--provenance=mode=max", "--sbom=true")
+		// The docker-container driver caches the build result but does not export
+		// it unless --push or --load is explicitly specified.
+		if push && len(ctr.PushTo) > 0 {
+			// Multi-registry: add every push_to ref as a --tag flag so buildx
+			// pushes to all registries in a single invocation.
+			allRefs := allImageRefsForContainer(ctr, tag, registries)
+			for _, ref := range allRefs[1:] {
+				args = append(args, "--tag", ref)
+			}
+			args = append(args, "--push")
+		} else if len(ctr.Platforms) <= 1 {
+			// Single-platform with no push (or no push_to): load into local daemon.
+			// Multi-platform + no-push: --load is unsupported; leave in buildkit cache.
+			args = append(args, "--load")
+		}
 	}
 
 	args = append(args, ".")
@@ -267,3 +283,27 @@ func imageRefForContainer(ctr config.CIContainerTarget, tag string, registries [
 	}
 	return ctr.Name + ":" + tag
 }
+
+// allImageRefsForContainer returns image refs for every registry listed in push_to[].
+// Falls back to local name:tag when push_to is empty.
+// Used by hardened buildx builds to populate multiple --tag flags so all registries
+// are pushed in a single buildx invocation.
+func allImageRefsForContainer(ctr config.CIContainerTarget, tag string, registries []config.CIRegistry) []string {
+	if len(ctr.PushTo) == 0 {
+		return []string{ctr.Name + ":" + tag}
+	}
+	regMap := make(map[string]string, len(registries))
+	for _, reg := range registries {
+		regMap[reg.Name] = reg.Path
+	}
+	refs := make([]string, 0, len(ctr.PushTo))
+	for _, regName := range ctr.PushTo {
+		if path, ok := regMap[regName]; ok {
+			refs = append(refs, path+"/"+ctr.Name+":"+tag)
+		} else {
+			// Fall back to raw registry name when path not configured.
+			refs = append(refs, regName+"/"+ctr.Name+":"+tag)
+		}
+	}
+	return refs
+}

cmd/wfctl/build_image_test.go

@@ -156,7 +156,203 @@ func TestRunBuildImage_NotHardenedNoProvenanceArgs(t *testing.T) {
 	}
 }
 
-// TestRunBuildImage_HardenedUsesBuildx verifies hardened=true produces "docker buildx build".
+// TestRunBuildImage_HardenedPushFlag verifies that --push passed to runBuildImage
+// adds --push to the docker buildx build args in hardened mode when push_to is set.
+func TestRunBuildImage_HardenedPushFlag(t *testing.T) {
+	dir := t.TempDir()
+	cfg := `ci:
+  registries:
+    - name: docr
+      type: do
+      path: registry.digitalocean.com/myorg
+  build:
+    security:
+      hardened: true
+    containers:
+      - name: app
+        method: dockerfile
+        dockerfile: Dockerfile
+        push_to:
+          - docr
+`
+	cfgPath := filepath.Join(dir, "ci.yaml")
+	if err := os.WriteFile(cfgPath, []byte(cfg), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("WFCTL_BUILD_DRY_RUN", "1")
+	t.Setenv("DOCKER_BUILDKIT", "1")
+
+	var buf bytes.Buffer
+	if err := runBuildImageWithOutput([]string{"--config", cfgPath, "--push"}, &buf); err != nil {
+		t.Fatalf("hardened --push dry-run: %v", err)
+	}
+
+	out := buf.String()
+	if !strings.Contains(out, "--push") {
+		t.Errorf("expected --push in hardened dry-run output with --push flag, got: %q", out)
+	}
+	if strings.Contains(out, "--load") {
+		t.Errorf("expected no --load when --push is set, got: %q", out)
+	}
+}
+
+// TestRunBuildImage_HardenedPushNoPushTo verifies that without push_to, hardened
+// buildx falls back to --load (not --push), even when --push is requested.
+func TestRunBuildImage_HardenedPushNoPushTo(t *testing.T) {
+	dir := t.TempDir()
+	cfg := `ci:
+  build:
+    security:
+      hardened: true
+    containers:
+      - name: app
+        method: dockerfile
+        dockerfile: Dockerfile
+`
+	cfgPath := filepath.Join(dir, "ci.yaml")
+	if err := os.WriteFile(cfgPath, []byte(cfg), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("WFCTL_BUILD_DRY_RUN", "1")
+	t.Setenv("DOCKER_BUILDKIT", "1")
+
+	var buf bytes.Buffer
+	if err := runBuildImageWithOutput([]string{"--config", cfgPath, "--push"}, &buf); err != nil {
+		t.Fatalf("hardened --push no-push_to dry-run: %v", err)
+	}
+
+	out := buf.String()
+	// No push_to → should not add --push (would try to push a local-only name).
+	if strings.Contains(out, " --push") {
+		t.Errorf("expected no --push when push_to is empty, got: %q", out)
+	}
+	// Single-platform fallback → should add --load.
+	if !strings.Contains(out, "--load") {
+		t.Errorf("expected --load for single-platform no-push_to, got: %q", out)
+	}
+}
+
+// TestRunBuildImage_HardenedMultiRegistryPush verifies that multi-registry push
+// (push_to: [docr, ghcr]) adds all registry refs as --tag flags so buildx pushes
+// to every registry in a single invocation.
+func TestRunBuildImage_HardenedMultiRegistryPush(t *testing.T) {
+	dir := t.TempDir()
+	cfg := `ci:
+  registries:
+    - name: docr
+      type: do
+      path: registry.digitalocean.com/myorg
+    - name: ghcr
+      type: github
+      path: ghcr.io/myorg
+  build:
+    security:
+      hardened: true
+    containers:
+      - name: app
+        method: dockerfile
+        dockerfile: Dockerfile
+        push_to:
+          - docr
+          - ghcr
+`
+	cfgPath := filepath.Join(dir, "ci.yaml")
+	if err := os.WriteFile(cfgPath, []byte(cfg), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("WFCTL_BUILD_DRY_RUN", "1")
+	t.Setenv("DOCKER_BUILDKIT", "1")
+
+	var buf bytes.Buffer
+	if err := runBuildImageWithOutput([]string{"--config", cfgPath, "--push"}, &buf); err != nil {
+		t.Fatalf("hardened multi-registry push dry-run: %v", err)
+	}
+
+	out := buf.String()
+	if !strings.Contains(out, "registry.digitalocean.com/myorg/app") {
+		t.Errorf("expected docr registry ref in output, got: %q", out)
+	}
+	if !strings.Contains(out, "ghcr.io/myorg/app") {
+		t.Errorf("expected ghcr registry ref in output, got: %q", out)
+	}
+	if !strings.Contains(out, "--push") {
+		t.Errorf("expected --push in multi-registry output, got: %q", out)
+	}
+}
+
+// TestRunBuildImage_HardenedNoPushAddsLoad verifies that without --push, hardened
+// single-platform buildx invocations include --load so the image is available in
+// the local daemon.
+func TestRunBuildImage_HardenedNoPushAddsLoad(t *testing.T) {
+	dir := t.TempDir()
+	cfg := `ci:
+  build:
+    security:
+      hardened: true
+    containers:
+      - name: app
+        method: dockerfile
+        dockerfile: Dockerfile
+`
+	cfgPath := filepath.Join(dir, "ci.yaml")
+	if err := os.WriteFile(cfgPath, []byte(cfg), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("WFCTL_BUILD_DRY_RUN", "1")
+	t.Setenv("DOCKER_BUILDKIT", "1")
+
+	var buf bytes.Buffer
+	// Note: no --push flag — default is no push (load only).
+	if err := runBuildImageWithOutput([]string{"--config", cfgPath}, &buf); err != nil {
+		t.Fatalf("hardened no-push dry-run: %v", err)
+	}
+
+	out := buf.String()
+	if !strings.Contains(out, "--load") {
+		t.Errorf("expected --load in hardened dry-run output without --push flag, got: %q", out)
+	}
+	if strings.Contains(out, " --push") {
+		t.Errorf("expected no --push when push flag is not set, got: %q", out)
+	}
+}
+
+// TestRunBuildImage_HardenedMultiPlatformNoPushNoLoad verifies that multi-platform
+// hardened builds without --push do NOT add --load (unsupported by buildx) and leave
+// the result in buildkit cache instead.
+func TestRunBuildImage_HardenedMultiPlatformNoPushNoLoad(t *testing.T) {
+	dir := t.TempDir()
+	cfg := `ci:
+  build:
+    security:
+      hardened: true
+    containers:
+      - name: app
+        method: dockerfile
+        dockerfile: Dockerfile
+        platforms:
+          - linux/amd64
+          - linux/arm64
+`
+	cfgPath := filepath.Join(dir, "ci.yaml")
+	if err := os.WriteFile(cfgPath, []byte(cfg), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("WFCTL_BUILD_DRY_RUN", "1")
+	t.Setenv("DOCKER_BUILDKIT", "1")
+
+	var buf bytes.Buffer
+	if err := runBuildImageWithOutput([]string{"--config", cfgPath}, &buf); err != nil {
+		t.Fatalf("hardened multi-platform no-push dry-run: %v", err)
+	}
+
+	out := buf.String()
+	if strings.Contains(out, "--load") {
+		t.Errorf("expected no --load for multi-platform no-push (unsupported), got: %q", out)
+	}
+	if strings.Contains(out, " --push") {
+		t.Errorf("expected no --push for multi-platform no-push, got: %q", out)
+	}
+}
 func TestRunBuildImage_HardenedUsesBuildx(t *testing.T) {
 	dir := t.TempDir()
 	cfg := `ci: