homelab/documentation/plans/plan-autoDeployEnrichment.md

documentation/plans/plan-autoDeployEnrichment.md

# 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