feat(build): support optional BuildKit secrets

README.md

@@ -50,6 +50,9 @@ Use manifest version 2 when one image serves multiple applications or Production
       "image": "example/web",
       "dockerfile": "Dockerfile",
       "buildArgs": { "BUILD_SHA": "$sha12" },
+      "buildSecrets": {
+        "framework-build-key": "FRAMEWORK_BUILD_KEY"
+      },
       "requiredFiles": ["/app/server.js"]
     }
   ],
@@ -87,4 +90,10 @@ Use manifest version 2 when one image serves multiple applications or Production
 }
 ```
 
+`buildSecrets` is optional and maps a BuildKit secret mount ID to the name of
+an Actions secret exposed to the workflow environment. Values are passed to
+`docker build` through `--secret id=...,env=...`; they are never included in
+the command line as build arguments. The Dockerfile consumes them with
+`RUN --mount=type=secret,id=<id>,required=true ...`.
+
 Candidate pipelines build every artifact once, push `sha-<commit>`, resolve the registry digest and deploy applications in dependency order. A pull request into a promotion branch must originate from `source.branch`; it pulls and verifies the already tested `sha-<commit>` candidates without rebuilding or deploying them. Promotion pushes require a merge parent with an identical Git tree, pull the existing candidate, verify required container files, add the SemVer alias, deploy the exact digests, create the immutable tag and publish the canonical Gitea release. Tag creation does not trigger another scoped pipeline because the workflow listens only to branch pushes.