ci: wait for concurrent candidate publication

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;
@@ -550,11 +577,46 @@ function buildArtifact({ artifact, registry, sha, workspace, dockerEnv, validati
   return { artifact, taggedImage, digest, exactImage: `${registry}/${artifact.image}@${digest}` };
 }
 
-function pullCandidateArtifact({ artifact, registry, sourceSha, workspace, dockerEnv }) {
+const PROMOTION_PR_CANDIDATE_PULL_ATTEMPTS = 40;
+const PROMOTION_PR_CANDIDATE_PULL_RETRY_MS = 10_000;
+
+export async function pullCandidateArtifact({
+  artifact,
+  registry,
+  sourceSha,
+  workspace,
+  dockerEnv,
+  pullAttempts = 1,
+  pullRetryMs = 0,
+  runCommand = run,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
   const taggedImage = `${registry}/${artifact.image}:sha-${sourceSha}`;
-  run("docker", ["pull", taggedImage], { cwd: workspace, env: dockerEnv });
+  if (!Number.isInteger(pullAttempts) || pullAttempts < 1) {
+    throw new Error("Candidate pull attempts must be a positive integer.");
+  }
+  if (!Number.isFinite(pullRetryMs) || pullRetryMs < 0) {
+    throw new Error("Candidate pull retry delay must be a non-negative number.");
+  }
+  for (let attempt = 1; attempt <= pullAttempts; attempt += 1) {
+    try {
+      runCommand("docker", ["pull", taggedImage], { cwd: workspace, env: dockerEnv });
+      break;
+    } catch (error) {
+      if (attempt === pullAttempts) {
+        throw new Error(
+          `Candidate ${taggedImage} did not become available after ${pullAttempts} attempt(s).`,
+          { cause: error },
+        );
+      }
+      console.log(
+        `Candidate ${taggedImage} is not available yet (${attempt}/${pullAttempts}); retrying in ${pullRetryMs}ms.`,
+      );
+      await sleep(pullRetryMs);
+    }
+  }
   verifyRequiredContainerFiles(taggedImage, artifact.requiredFiles, { cwd: workspace, env: dockerEnv });
-  const repoDigests = run(
+  const repoDigests = runCommand(
     "docker",
     ["image", "inspect", "--format", "{{range .RepoDigests}}{{println .}}{{end}}", taggedImage],
     { cwd: workspace, env: dockerEnv, capture: true },
@@ -605,9 +667,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,
@@ -671,12 +736,14 @@ async function executeVersion2({ config, pipeline, eventName, sha, workspace })
       const release = loadRelease(workspace, pipeline.release);
       const artifacts = new Map();
       for (const artifact of pipeline.artifacts) {
-        artifacts.set(artifact.name, pullCandidateArtifact({
+        artifacts.set(artifact.name, await pullCandidateArtifact({
           artifact,
           registry,
           sourceSha: sha,
           workspace,
           dockerEnv,
+          pullAttempts: PROMOTION_PR_CANDIDATE_PULL_ATTEMPTS,
+          pullRetryMs: PROMOTION_PR_CANDIDATE_PULL_RETRY_MS,
         }));
       }
       console.log(`Validated ${release.tag} against ${artifacts.size} tested candidate artifact(s) from ${sourceBranch} at ${sha}; no rebuild or deployment performed.`);
@@ -688,7 +755,7 @@ async function executeVersion2({ config, pipeline, eventName, sha, workspace })
     const release = loadRelease(workspace, pipeline.release);
     const artifacts = new Map();
     for (const artifact of pipeline.artifacts) {
-      artifacts.set(artifact.name, pullCandidateArtifact({
+      artifacts.set(artifact.name, await pullCandidateArtifact({
         artifact,
         registry,
         sourceSha,

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

@@ -6,6 +6,8 @@ import {
   deployExactImage,
   expandTokens,
   mergeEnvironment,
+  pullCandidateArtifact,
+  resolveSecretEnvironment,
   orderApplications,
   resolveDeploymentBranch,
   resolvePullRequestHeadBranch,
@@ -98,6 +100,46 @@ test("production pull requests validate tested candidates without rebuilding", (
   );
 });
 
+test("production pull requests wait for a concurrently published candidate", async () => {
+  const registry = "gitea.nuvisphere.de";
+  const artifact = {
+    name: "webapp",
+    image: "innomieter/webapp",
+    requiredFiles: [],
+  };
+  const sourceSha = "1234567890abcdef1234567890abcdef12345678";
+  const digest = `sha256:${"a".repeat(64)}`;
+  const sleeps = [];
+  let pullCalls = 0;
+  const runCommand = (_command, args) => {
+    if (args[0] === "pull") {
+      pullCalls += 1;
+      if (pullCalls < 3) throw new Error("manifest unknown");
+      return "";
+    }
+    if (args[0] === "image") {
+      return `${registry}/${artifact.image}@${digest}\n`;
+    }
+    throw new Error(`Unexpected Docker command: ${args.join(" ")}`);
+  };
+
+  const result = await pullCandidateArtifact({
+    artifact,
+    registry,
+    sourceSha,
+    workspace: "/workspace",
+    dockerEnv: {},
+    pullAttempts: 3,
+    pullRetryMs: 25,
+    runCommand,
+    sleep: async (ms) => sleeps.push(ms),
+  });
+
+  assert.equal(pullCalls, 3);
+  assert.deepEqual(sleeps, [25, 25]);
+  assert.equal(result.exactImage, `${registry}/${artifact.image}@${digest}`);
+});
+
 test("validates OCI paths and repository-local build paths", () => {
   assert.equal(validateTarget({ name: "Web", image: "Owner/Web", appId: "app-1" }).image, "owner/web");
   assert.throws(() => validateTarget({ name: "Web", image: "owner/web", appId: "app-1", context: "../secret" }), /inside/);
@@ -170,6 +212,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

@@ -13,7 +13,7 @@ concurrency:
 
 jobs:
   build_and_deploy:
-    name: Build once and deploy exact digest
+    name: ${{ gitea.event_name == 'pull_request' && 'Validate existing candidate without deployment' || gitea.event_name == 'push' && 'Build, publish and deploy exact candidate' || 'Validate or redeploy declared pipeline' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -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

@@ -88,3 +88,8 @@ Use manifest version 2 when one image serves multiple applications or Production
 ```
 
 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.
+
+When a promotion pull request and its source-branch push start concurrently, the
+pull-request check waits for the immutable candidate tag to become available.
+This bounded retry applies only to promotion pull requests; an actual promotion
+still fails immediately when its tested candidate is missing.