feat: add target input for multi-stage Docker builds

Allows callers to specify a Docker build target stage (e.g. target: production)
for multi-stage Dockerfiles. Empty default preserves backward compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitea/workflows/build-push.yaml

@@ -29,11 +29,26 @@ on:
         required: false
         type: string
         default: ""
+      target:
+        description: "Docker build target stage (for multi-stage builds)"
+        required: false
+        type: string
+        default: ""
       runner:
         description: "Runner label to use (e.g. ubuntu-latest, self-hosted-arm64). ARM64 builds use QEMU emulation on amd64 runners by default — set this to a native ARM64 runner for faster Rust/heavy builds."
         required: false
         type: string
         default: "ubuntu-latest"
+      environment-tag:
+        description: "Mutable environment tag to push (e.g. prod, staging, dev). If empty, auto-detected from branch: main/master→prod, staging→staging, dev→dev."
+        required: false
+        type: string
+        default: ""
+      version-tag:
+        description: "Pinned version tag to push (e.g. dev-v123). Used for node-specific testing."
+        required: false
+        type: string
+        default: ""
     secrets:
       REGISTRY_USER:
         required: true
@@ -77,7 +92,11 @@ jobs:
           images: ${{ inputs.image-name }}
           tags: |
             type=sha,prefix=sha-
-            type=raw,value=latest,enable={{is_default_branch}}
+            type=raw,value=prod,enable=${{ gitea.ref == 'refs/heads/main' || gitea.ref == 'refs/heads/master' }}
+            type=raw,value=staging,enable=${{ gitea.ref == 'refs/heads/staging' }}
+            type=raw,value=dev,enable=${{ gitea.ref == 'refs/heads/dev' }}
+            type=raw,value=${{ inputs.environment-tag }},enable=${{ inputs.environment-tag != '' }}
+            type=raw,value=${{ inputs.version-tag }},enable=${{ inputs.version-tag != '' }}
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
 
@@ -89,6 +108,7 @@ jobs:
         with:
           context: ${{ inputs.context }}
           file: ${{ inputs.context }}/${{ inputs.dockerfile }}
+          target: ${{ inputs.target || '' }}
           platforms: ${{ inputs.platforms }}
           push: true
           tags: ${{ steps.meta.outputs.tags }}

.gitea/workflows/deploy-k8s.yaml

@@ -1,12 +1,17 @@
-# Reusable workflow: Update image tag in wectrl-k8s-cluster repo (GitOps deploy)
+# Reusable workflow: Bump deploy-timestamp in wectrl-k8s-cluster repo (GitOps deploy)
 # Usage: uses: wectrl-net/ci-templates/.gitea/workflows/deploy-k8s.yaml@main
+#
+# With environment-based mutable tags (:prod, :staging, :dev), the image tag in
+# k8s manifests stays constant. To trigger a rollout after pushing a new image,
+# this workflow bumps the deploy-timestamp pod annotation, which causes ArgoCD to
+# detect a diff and sync the deployment.
 name: Deploy to K8s (GitOps)
 
 on:
   workflow_call:
     inputs:
       image-name:
-        description: "Full image name (e.g. git.wectrl.net/wectrl-net/my-service)"
+        description: "Full image name (e.g. git.wectrl.net/wectrl-net/my-service) — used in commit message for traceability"
         required: true
         type: string
       deploy-paths:
@@ -40,13 +45,13 @@ jobs:
           wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.44.1/yq_linux_amd64
           chmod +x /usr/local/bin/yq
 
-      - name: Update image tag in cluster repo
+      - name: Bump deploy-timestamp in cluster repo
         run: |
           set -euo pipefail
 
           SHA="${{ gitea.sha }}"
           SHORT_SHA="${SHA:0:7}"
-          IMAGE_TAG="sha-${SHORT_SHA}"
+          TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
           RUN_URL="${{ gitea.server_url }}/${{ gitea.repository }}/actions/runs/${{ gitea.run_id }}"
 
           git clone https://${{ secrets.GIT_USER }}:${{ secrets.GIT_TOKEN }}@git.wectrl.net/${{ inputs.k8s-repo }}.git
@@ -56,16 +61,17 @@ jobs:
           git config user.name "Gitea CI"
 
           for DEPLOY_PATH in ${{ inputs.deploy-paths }}; do
-            yq -i '(.spec.template.spec.containers[].image | select(test("^${{ inputs.image-name }}:"))) = "${{ inputs.image-name }}:'"${IMAGE_TAG}"'"' \
+            yq -i '.spec.template.metadata.annotations.deploy-timestamp = "'"${TIMESTAMP}"'"' \
               "${DEPLOY_PATH}"
             git add "${DEPLOY_PATH}"
           done
 
           if git diff --staged --quiet; then
-            echo "No image tag changes to commit"
+            echo "No changes to commit"
           else
-            git commit -m "deploy: ${{ inputs.service-name }} ${IMAGE_TAG}
+            git commit -m "deploy: ${{ inputs.service-name }} sha-${SHORT_SHA}
 
+Timestamp: ${TIMESTAMP}
 Source: ${SHA}
 Run: ${RUN_URL}"
             git push origin main