134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
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": "<stack-name>" }
|
|
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": "<name>" }
|
|
Headers: X-Api-Key: <key>, X-Api-Secret: <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. |