feat(build): support optional BuildKit secrets

Adds validated opt-in mapping from Gitea Actions secrets to QuickStack runtime environment variables.

.gitea/actions/quickstack-oci/deploy.mjs

@@ -87,6 +87,33 @@ export function mergeEnvironment(source, overrides = {}) {
   return rows.map((row) => row.raw ?? `${row.key}=${row.value}`).join("\n");
 }
 
+export function resolveSecretEnvironment(secretEnvironment = {}, environment = process.env) {
+  if (
+    secretEnvironment === null ||
+    typeof secretEnvironment !== "object" ||
+    Array.isArray(secretEnvironment)
+  ) {
+    throw new Error("secretEnvironment must be an object.");
+  }
+
+  const resolved = {};
+  for (const [runtimeKey, rawSecretName] of Object.entries(secretEnvironment)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(runtimeKey)) {
+      throw new Error(`Invalid secret environment key ${runtimeKey}.`);
+    }
+    const secretName = String(rawSecretName);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(secretName)) {
+      throw new Error(`Invalid Actions secret name for ${runtimeKey}.`);
+    }
+    const value = environment[secretName];
+    if (value === undefined || String(value).length === 0) {
+      throw new Error(`Missing Actions secret ${secretName} for runtime environment ${runtimeKey}.`);
+    }
+    resolved[runtimeKey] = String(value);
+  }
+  return resolved;
+}
+
 async function readBody(response) {
   const text = await response.text();
   if (!text) return null;
@@ -347,6 +374,32 @@ function validateImagePath(value, name) {
   return image;
 }
 
+function normalizeBuildSecrets(buildSecrets = {}) {
+  if (buildSecrets === null || typeof buildSecrets !== "object" || Array.isArray(buildSecrets)) {
+    throw new Error("buildSecrets must be an object.");
+  }
+  return Object.fromEntries(
+    Object.entries(buildSecrets).map(([id, rawEnvironmentName]) => {
+      if (!/^[A-Za-z0-9_.-]+$/.test(id)) throw new Error(`Invalid BuildKit secret ID ${id}.`);
+      const environmentName = String(rawEnvironmentName);
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(environmentName)) {
+        throw new Error(`Invalid Actions secret environment name for BuildKit secret ${id}.`);
+      }
+      return [id, environmentName];
+    }),
+  );
+}
+
+export function resolveBuildSecretArguments(buildSecrets = {}, environment = process.env) {
+  return Object.entries(normalizeBuildSecrets(buildSecrets)).flatMap(([id, environmentName]) => {
+    const value = environment[environmentName];
+    if (value === undefined || String(value).length === 0) {
+      throw new Error(`Missing Actions secret ${environmentName} for BuildKit secret ${id}.`);
+    }
+    return ["--secret", `id=${id},env=${environmentName}`];
+  });
+}
+
 export function validateArtifact(artifact) {
   const name = requiredString(artifact.name, "Artifact name");
   const requiredFiles = (artifact.requiredFiles ?? []).map((file) => {
@@ -369,6 +422,7 @@ export function validateArtifact(artifact) {
     dockerfile: safeRelative(artifact.dockerfile ?? "Dockerfile", `Dockerfile for ${name}`),
     context: safeRelative(artifact.context ?? ".", `Build context for ${name}`),
     buildArgs,
+    buildSecrets: normalizeBuildSecrets(artifact.buildSecrets),
     requiredFiles,
   };
 }
@@ -539,6 +593,7 @@ function buildArtifact({ artifact, registry, sha, workspace, dockerEnv, validati
   for (const [key, value] of Object.entries(artifact.buildArgs)) {
     buildArgs.push("--build-arg", `${key}=${expandTokens(value, { sha })}`);
   }
+  buildArgs.push(...resolveBuildSecretArguments(artifact.buildSecrets, dockerEnv));
   buildArgs.push(artifact.context);
   console.log(`Building ${artifact.name} from ${artifact.dockerfile} as ${taggedImage}.`);
   run("docker", buildArgs, { cwd: workspace, env: dockerEnv });
@@ -605,9 +660,12 @@ function promoteArtifactAliases(artifacts, releaseTag, options) {
 async function deployApplications({ applications, artifacts, sha, client }) {
   for (const application of applications) {
     const artifact = artifacts.get(application.artifact);
-    const environment = Object.fromEntries(
+    const environment = {
+      ...Object.fromEntries(
         Object.entries(application.environment ?? {}).map(([key, value]) => [key, expandTokens(value, { sha })]),
-    );
+      ),
+      ...resolveSecretEnvironment(application.secretEnvironment),
+    };
     const result = await deployExactImage({
       client,
       appId: application.appId,

.gitea/actions/quickstack-oci/deploy.test.mjs

@@ -6,6 +6,8 @@ import {
   deployExactImage,
   expandTokens,
   mergeEnvironment,
+  resolveBuildSecretArguments,
+  resolveSecretEnvironment,
   orderApplications,
   resolveDeploymentBranch,
   resolvePullRequestHeadBranch,
@@ -150,6 +152,34 @@ test("version 2 validates promotion contracts and token expansion", () => {
   );
 });
 
+test("passes declared Actions secrets to Docker only through BuildKit secret mounts", () => {
+  const secretValue = "must-not-appear-in-docker-arguments";
+  const artifact = validateArtifact({
+    name: "web",
+    image: "owner/web",
+    buildSecrets: {
+      "next-server-actions-encryption-key": "NEXT_SERVER_ACTIONS_ENCRYPTION_KEY",
+    },
+  });
+  const args = resolveBuildSecretArguments(artifact.buildSecrets, {
+    NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: secretValue,
+  });
+
+  assert.deepEqual(args, [
+    "--secret",
+    "id=next-server-actions-encryption-key,env=NEXT_SERVER_ACTIONS_ENCRYPTION_KEY",
+  ]);
+  assert.doesNotMatch(JSON.stringify(args), new RegExp(secretValue));
+  assert.throws(
+    () => resolveBuildSecretArguments(artifact.buildSecrets, {}),
+    /Missing Actions secret NEXT_SERVER_ACTIONS_ENCRYPTION_KEY/,
+  );
+  assert.throws(
+    () => validateArtifact({ name: "web", image: "owner/web", buildSecrets: { "../invalid": "SECRET" } }),
+    /Invalid BuildKit secret ID/,
+  );
+});
+
 test("application dependencies reject missing nodes and cycles", () => {
   assert.throws(
     () => orderApplications([{ name: "web", dependsOn: ["missing"] }]),
@@ -170,6 +200,24 @@ test("preserves response-only fields and existing environment secrets safely", (
   assert.equal(mergeEnvironment(app().envVars, { ENVIRONMENT: "new" }), "SECRET=preserved\nENVIRONMENT=new");
 });
 
+test("maps only explicitly declared Actions secrets into runtime environment", () => {
+  assert.deepEqual(
+    resolveSecretEnvironment(
+      { MINIO_ENDPOINT: "MINIO_ENDPOINT", MINIO_REGION: "MINIO_REGION" },
+      { MINIO_ENDPOINT: "https://minio.example.test", MINIO_REGION: "us-east-1" },
+    ),
+    { MINIO_ENDPOINT: "https://minio.example.test", MINIO_REGION: "us-east-1" },
+  );
+  assert.throws(
+    () => resolveSecretEnvironment({ MINIO_ENDPOINT: "MINIO_ENDPOINT" }, {}),
+    /Missing Actions secret MINIO_ENDPOINT/,
+  );
+  assert.throws(
+    () => resolveSecretEnvironment({ "INVALID-KEY": "MINIO_ENDPOINT" }, { MINIO_ENDPOINT: "value" }),
+    /Invalid secret environment key/,
+  );
+});
+
 test("postflight waits for the exact expected identity", async () => {
   let attempt = 0;
   const result = await verifyEndpoint(

.gitea/scoped_workflows/quickstack-oci.yml

@@ -34,3 +34,19 @@ jobs:
           QUICKSTACK_API_TOKEN: ${{ secrets.QUICKSTACK_API_TOKEN }}
           QUICKSTACK_BASE_URL: https://server.nuvisphere.de
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          MINIO_ENDPOINT: ${{ secrets.MINIO_ENDPOINT }}
+          NEXT_PUBLIC_MINIO_ENDPOINT: ${{ secrets.NEXT_PUBLIC_MINIO_ENDPOINT }}
+          MINIO_REGION: ${{ secrets.MINIO_REGION }}
+          MINIO_ROOT_USER: ${{ secrets.MINIO_ROOT_USER }}
+          MINIO_ROOT_PASSWORD: ${{ secrets.MINIO_ROOT_PASSWORD }}
+          MINIO_TLS_REJECT_UNAUTHORIZED: ${{ secrets.MINIO_TLS_REJECT_UNAUTHORIZED }}
+          MINIO_AVATAR_BUCKET: ${{ secrets.MINIO_AVATAR_BUCKET }}
+          REDIS_URL: ${{ secrets.REDIS_URL }}
+          WEB_PUSH_PUBLIC_KEY: ${{ secrets.WEB_PUSH_PUBLIC_KEY }}
+          WEB_PUSH_PRIVATE_KEY: ${{ secrets.WEB_PUSH_PRIVATE_KEY }}
+          WEB_PUSH_SUBJECT: ${{ secrets.WEB_PUSH_SUBJECT }}
+          SMTP_HOST: ${{ secrets.SMTP_HOST }}
+          SMTP_PORT: ${{ secrets.SMTP_PORT }}
+          SMTP_SECURE: ${{ secrets.SMTP_SECURE }}
+          SMTP_USER: ${{ secrets.SMTP_USER }}
+          SMTP_PASS: ${{ secrets.SMTP_PASS }}

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.