From d8b628cd637a53bd948acdef439db45189566a19 Mon Sep 17 00:00:00 2001
From: admin <alec@bryanmail.net>
Date: Sat, 20 Jun 2026 23:23:35 -0700
Subject: [PATCH] Add woodpecker secrets reference (manual management only)

---
 secrets/woodpecker.secrets.example | 54 ++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 secrets/woodpecker.secrets.example

diff --git a/secrets/woodpecker.secrets.example b/secrets/woodpecker.secrets.example
new file mode 100644
index 0000000..6792b6e
--- /dev/null
+++ b/secrets/woodpecker.secrets.example
@@ -0,0 +1,54 @@
+# woodpecker Stack — Secrets Reference
+# Source: woodpecker.env
+#
+# ⚠️  MANUAL MANAGEMENT ONLY — Woodpecker cannot provision its own secrets.
+#     This would be a circular dependency: the pipeline that provisions secrets
+#     depends on Woodpecker running, which depends on these secrets existing.
+#
+#     These secrets must always be managed manually on the host at:
+#     /volume1/docker/compose-files/woodpecker.env
+#
+#     Do NOT add these to Woodpecker's secret store for use in pipelines.
+#     They are documented here only for reference and disaster recovery.
+
+# ── SECRETS (manual management on host only) ──────────────────────────────────
+
+# Variable:  WOODPECKER_GITEA_CLIENT
+# Used for:  Gitea OAuth2 application client ID
+# Find in:   Gitea → Settings → Applications → OAuth2 Applications → Woodpecker
+# NOTE:      This is a UUID, not a password, but treat as sensitive
+
+# Variable:  WOODPECKER_GITEA_SECRET
+# Used for:  Gitea OAuth2 application client secret
+# Find in:   Gitea → Settings → Applications → OAuth2 Applications → Woodpecker
+# NOTE:      Regenerate in Gitea if compromised, then update woodpecker.env + redeploy
+
+# Variable:  WOODPECKER_AGENT_SECRET
+# Used for:  Shared secret between Woodpecker server and agents (gRPC auth)
+# Generate:  openssl rand -hex 32
+# NOTE:      Must match between server and all agent containers. Changing requires
+#            redeploying the entire woodpecker stack simultaneously.
+
+# Variable:  DB_USER
+# Used for:  Woodpecker PostgreSQL username (woodpecker)
+# NOTE:      Not sensitive, but kept in .env for consistency
+
+# Variable:  DB_PASS
+# Used for:  Woodpecker PostgreSQL password
+# NOTE:      Must be URL-encoded when used in DATABASE_DATASOURCE
+#            Use: python3 -c "import urllib.parse; print(urllib.parse.quote('yourpass', safe=''))"
+
+# ── NON-SECRETS ───────────────────────────────────────────────────────────────
+
+# DB_USER    Database username (woodpecker) — not sensitive
+
+# ── Recovery procedure ────────────────────────────────────────────────────────
+#
+# If woodpecker.env is lost:
+#
+# 1. Regenerate WOODPECKER_GITEA_SECRET in Gitea UI
+# 2. Generate new WOODPECKER_AGENT_SECRET: openssl rand -hex 32
+# 3. Retrieve DB_PASS from postgresql.env (woodpecker user password)
+# 4. Recreate woodpecker.env on host
+# 5. Redeploy: docker stack deploy -c woodpecker.yaml woodpecker
+# 6. Re-add secrets to Woodpecker UI for all pipelines