From e0a6b7d2334bda3e281c215cb068b06bef797764 Mon Sep 17 00:00:00 2001
From: admin <alec@bryanmail.net>
Date: Mon, 27 Jul 2026 13:35:13 -0700
Subject: [PATCH] deploy.yml: fix pipeline compile error 'missing closing
 brace' -- the documentation comment itself contained a literal dollar-brace
 sequence with invalid contents (dollar-brace CI_...), which Woodpecker's
 substitution engine parses even inside comments. Rewrote header to describe
 the rules in words without any literal dollar-brace sequences. Also removed
 backtick-quoted dollar-brace remnants from the vaultwarden case comment.

---
 .woodpecker/deploy.yml | 37 +++++++++++++++++++++----------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/.woodpecker/deploy.yml b/.woodpecker/deploy.yml
index 0077d71..477626d 100644
--- a/.woodpecker/deploy.yml
+++ b/.woodpecker/deploy.yml
@@ -5,22 +5,27 @@ when:
 # ─────────────────────────────────────────────────────────────────────────────
 # IMPORTANT — Woodpecker variable substitution rules (learned the hard way):
 #
-#   Woodpecker pre-processes command strings BEFORE the shell runs them:
-#     - ${VAR}  is substituted at pipeline-compile time from Woodpecker's own
-#       metadata (CI_* vars). Secrets DO NOT exist in that map, so any braced
-#       reference to a secret-backed env var silently becomes an EMPTY STRING.
-#     - $$      is unescaped to a single $ and passed to the shell.
+#   Woodpecker pre-processes the ENTIRE yaml text (comments included!) before
+#   the shell runs anything:
+#     - A dollar sign followed by a braced variable name is substituted at
+#       pipeline-compile time from Woodpecker's own metadata (the CI_* vars).
+#       Secrets DO NOT exist in that map, so a braced reference to a
+#       secret-backed env var silently becomes an EMPTY STRING.
+#     - A double dollar sign is unescaped to a single dollar sign and passed
+#       through to the shell untouched.
 #
 #   Therefore:
-#     - Use ${CI_...} (braced, unescaped) ONLY for Woodpecker metadata vars.
-#     - Use $${VAR} for anything that must be resolved by the shell at runtime
-#       (i.e., every from_secret-backed environment variable).
-#     - Bare $VAR (no braces) also works for runtime resolution, but $${VAR}
-#       is preferred for anything adjacent to other characters.
+#     - Braced, single-dollar form: ONLY for Woodpecker CI_* metadata vars.
+#     - Double-dollar braced form: for everything that must be resolved by the
+#       shell at runtime (i.e., every from_secret-backed environment variable).
+#     - Bare single-dollar VAR (no braces) also passes through to the shell.
+#     - NEVER write a literal dollar-brace sequence in comments either — the
+#       substitution engine parses comments too and will fail the pipeline
+#       with "missing closing brace" on anything it cannot parse.
 #
 #   This was the root cause of a long-running "SWARM_MANAGER_IP secret is
-#   empty" failure: the braced references were being blanked at compile time
-#   before the shell ever saw them.
+#   empty" failure: braced references were blanked at compile time before the
+#   shell ever saw them.
 # ─────────────────────────────────────────────────────────────────────────────
 
 steps:
@@ -200,10 +205,10 @@ steps:
                 create_or_update_secret 'productivity_oidc_providers'       '$${PRODUCTIVITY_OIDC_PROVIDERS}'";;
             vaultwarden)
               # NOTE: vaultwarden_database_url cannot be rotated in-place — Swarm refuses
-              # to `docker secret rm` a secret referenced by a running service's spec.
-              # We provision under a versioned name (_v2) instead; vaultwarden.yaml maps
-              # it back to the same in-container filename via `target:`. The old secret
-              # is removed manually once the compose file cutover is confirmed healthy.
+              # to remove a secret referenced by a running service's spec. We provision
+              # under a versioned name instead; vaultwarden.yaml maps it back to the same
+              # in-container filename via target. The old secret is removed manually once
+              # the compose file cutover is confirmed healthy.
               ssh -o StrictHostKeyChecking=no root@$${SWARM_MANAGER_IP} "source /tmp/cs.sh
                 create_or_update_secret 'vaultwarden_admin_token'     '$${VAULTWARDEN_ADMIN_TOKEN}'
                 create_or_update_secret 'vaultwarden_database_url_v2' '$${VAULTWARDEN_DATABASE_URL}'";;