feat(docker-build): add secret-build-args for secret-valued build args

[samuelho-dev]

Why

GitHub Actions strips secret values from job outputs (security). A caller that resolves environment-scoped secrets in one job and passes them to this reusable workflow's build-args via needs.resolve-env.outputs.* therefore gets empty build-args — silently baking undefined into the image. Concretely: creativetoolkits' next build inlined NEXT_PUBLIC_* as undefined, crashing nextjs + payload-cms at runtime env validation.

Fix

New secret-build-args secret input, merged with plain build-args inside the build job (where secrets resolve — no cross-job output stripping). Values are read from an env var so they're not echoed; GitHub masks them in logs. docker/build-push-action de-dupes by key, secret args appended last so they win.

build-args bake into image layers (docker history), so this is documented as for public-anyway values (NEXT_PUBLIC_*), never true secrets.

Consumer

creativetoolkits cd.yaml build-frontend will pass NEXT_PUBLIC_* via secrets.secret-build-args instead of the broken resolve-env.outputs.* handoff (separate PR).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added support for secret build arguments in the Docker build workflow, enabling secure handling of sensitive build parameters during image creation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The workflow now supports secret build arguments via a new secret-build-args input. The parsing step merges plain and secret arguments, emitting both sets with secret arguments ordered last to ensure secret values take precedence on key collision.

Changes

Secret Docker Build Arguments

Layer / File(s)	Summary
Secret build arguments support .github/workflows/docker-build-push.yml	Declares secret-build-args as a workflow input and updates the build-arguments parser to merge plain build-args with secret-derived secret-build-args, appending secret args last for key-based de-duplication favoring secrets.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 With secrets held tight, no logs will betray,
Build args now whisper in their hidden way,
Plain and protected in one ordered flow,
Secrets take precedence, plain ones below!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and specifically describes the main change: adding a new secret-build-args feature for passing secret-valued build arguments to the Docker build workflow.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/docker-secret-build-args

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

.github/workflows/docker-build-push.yml (1)

82-91: ⚡ Quick win

Document secret-build-args in docs/USAGE.md.

This adds a new caller-facing workflow contract, but the current usage table in docs/USAGE.md:63-79 still only lists build-args. Please add secret-build-args there as well, including the “public values only” caveat, so consumers don’t miss the new path or treat it like a safe channel for real secrets.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/docker-build-push.yml around lines 82 - 91, Update
docs/USAGE.md to add the new workflow input "secret-build-args" alongside
"build-args" in the usage table (the section currently listing build-args);
document that it accepts KEY=VALUE pairs (one per line), that values are
resolved inside the job, and include the explicit caveat that build args bake
into image layers and therefore should only be used for public values (e.g.,
NEXT_PUBLIC_*) and never for true secrets; reference the workflow input name
"secret-build-args" and keep the phrasing consistent with the existing
"build-args" entry.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.github/workflows/docker-build-push.yml:
- Around line 82-91: Update docs/USAGE.md to add the new workflow input
"secret-build-args" alongside "build-args" in the usage table (the section
currently listing build-args); document that it accepts KEY=VALUE pairs (one per
line), that values are resolved inside the job, and include the explicit caveat
that build args bake into image layers and therefore should only be used for
public values (e.g., NEXT_PUBLIC_*) and never for true secrets; reference the
workflow input name "secret-build-args" and keep the phrasing consistent with
the existing "build-args" entry.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0e6e49aa-d013-4ecf-9799-29e185899a4a

📥 Commits

Reviewing files that changed from the base of the PR and between 9e3dbea and c16a76a.

📒 Files selected for processing (1)

• .github/workflows/docker-build-push.yml

[samuelho-dev]

Closing — research showed the correct fix is runtime injection of NEXT_PUBLIC_* (build once, deploy anywhere), which eliminates the build-arg path entirely rather than working around GitHub's secret-output stripping. The secret-build-args input would just prolong build-time inlining. Superseded by the runtime-injection refactor in creativetoolkits.