From 1545d7fd2eb55a2a58a125a9b3cd2f5a7ab34d47 Mon Sep 17 00:00:00 2001 From: nathan Date: Tue, 2 Jun 2026 12:14:51 -0400 Subject: [PATCH] plan-autoDeployEnrichment.md --- .../plans/plan-autoDeployEnrichment.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 documentation/plans/plan-autoDeployEnrichment.md diff --git a/documentation/plans/plan-autoDeployEnrichment.md b/documentation/plans/plan-autoDeployEnrichment.md new file mode 100644 index 0000000..03eebb5 --- /dev/null +++ b/documentation/plans/plan-autoDeployEnrichment.md @@ -0,0 +1,134 @@ +This is actually better than Option C as originally conceived. Komodo has a proper API client with a `DeployStack` execute endpoint — meaning the workflow doesn't need to construct webhook URLs at all. It can just call the Komodo API directly by stack name. + +There's even a GitHub Marketplace action (`komodoactions`) that wraps this exact pattern — API key + secret + stack name → deploy. That's compatible with Gitea Actions. + +Here's the plan document to commit before the Claude Code session: + +--- + +**`documentation/plans/plan-autoDeployEnrichment.md`** + +```markdown +# Plan: Auto-Deploy Enrichment (Option C — Komodo API) + +## Status +Planned. Runner setup in progress. Do not start Claude Code session until +the Gitea Actions runner is registered on Heimdall. + +## Goal +When a PR is merged to main in the homelab repo, automatically trigger a +redeploy in Komodo for each stack whose files changed — with no static +webhook map to maintain. + +## Approach +Use the Komodo REST API (DeployStack execute endpoint) instead of per-stack +webhook URLs. The workflow detects changed stack folders, extracts the stack +name, and calls Komodo directly by name. New stacks just work. + +## Why not the static webhook map (Option A) +Every new stack requires a manual workflow edit and a new Komodo webhook URL +to be copied. With ~30 stacks today and more coming, this is maintenance +overhead that compounds over time. + +## Why not the JSON secret (Option B) +Still manual — just moves the map from the workflow file into a Gitea secret. +Doesn't eliminate the problem. + +## Architecture + +### Trigger +Push to main branch of the homelab repo. + +### Path detection +Same logic as the existing workflow draft: +- Parse changed file paths for `nodes/{node}/{stack}/` pattern +- Extract stack name, deduplicate + +### Komodo API call +Instead of POSTing to a webhook URL, the workflow calls: +``` +POST https://komodo.castaldifamily.com/execute/DeployStack +Body: { "stack": "" } +Headers: X-Api-Key, X-Api-Secret +``` + +Stack name must exactly match the Komodo stack name. The folder name in the +homelab repo is used as the stack name — these should stay in sync. + +### Secrets required (Gitea repo settings) +| Secret | Value | +|---|---| +| KOMODO_URL | https://komodo.castaldifamily.com | +| KOMODO_API_KEY | From Komodo UI → Settings → Users → (service user) → Api Keys | +| KOMODO_API_SECRET | Same location — copy at creation, not shown again | + +### Service user setup (Komodo) +Create a dedicated service user for CI with minimal permissions: +- Stack: Execute (Deploy only) +- No write/delete permissions +- Settings → Users → New User (type: Service) + +## What the workflow replaces +The existing `.gitea/workflows/auto-deploy.yml` draft (static webhook map +with TODO entries). That file should be replaced entirely. + +## Claude Code session prompt + +``` +Read the following files before making any changes: +- .gitea/workflows/auto-deploy.yml (the existing draft to replace) +- documentation/plans/plan-autoDeployEnrichment.md +- README.md + +## Context +We are replacing the static webhook map workflow with one that calls the +Komodo API directly using DeployStack. Stack name is inferred from the +changed file path (nodes/{node}/{stack}/ → stack name). + +## Task + +### Step 1 — Confirm Komodo API endpoint +The expected endpoint is: + POST https://komodo.castaldifamily.com/execute/DeployStack + Body: { "stack": "" } + Headers: X-Api-Key: , X-Api-Secret: + +Before writing the workflow, confirm this matches the Komodo API docs +by checking: https://komo.do/docs/ecosystem/api +Show me the exact curl command you'll use in the workflow. + +### Step 2 — Rewrite the workflow +Replace .gitea/workflows/auto-deploy.yml with a new version that: +- Detects changed paths using the same nodes/{node}/{stack}/ logic +- Calls the Komodo DeployStack API for each changed stack by name +- Uses secrets: KOMODO_URL, KOMODO_API_KEY, KOMODO_API_SECRET +- Logs each stack triggered and its HTTP response code +- Fails with exit 1 if any API call returns non-2xx +- Handles the case where a stack name in the repo has no match in Komodo + gracefully (warn, don't fail — the stack may not be registered yet) + +### Step 3 — Update SOP-003 +Update documentation/SOPs/SOP-003-Gitea-Actions-Runner-Setup.md to +replace the KOMODO_WEBHOOK_SECRET secret with the three new secrets: +KOMODO_URL, KOMODO_API_KEY, KOMODO_API_SECRET. +Add a note on creating the Komodo service user with minimal permissions. + +### Step 4 — Update README +Reflect the new secret names in the Auto-Deploy section. + +## Constraints +- Do not touch compose files or .env files +- Show me the final workflow YAML before writing it to disk +- Run no tests (this repo has no test suite) +``` + +## Prerequisites before running Claude Code session +1. Gitea Actions runner registered on Heimdall (see SOP-003) +2. Komodo service user created with Stack Execute permissions +3. API key + secret copied and ready to add as Gitea secrets +4. Confirm stack names in homelab repo match stack names in Komodo UI +``` + +--- + +Commit that to `documentation/plans/plan-autoDeployEnrichment.md` and you're ready for the next session. The runner setup is still the blocker — nothing else can be tested until that's in place. \ No newline at end of file