docs: add deployment operation skills

2026-07-31 22:06:07 -04:00
parent 11406e3ec6
commit d98705cc9b
3 changed files with 90 additions and 0 deletions
@@ -0,0 +1,24 @@
+---
+name: deploy-staging
+description: Deploy SHD.build main to staging, inspect Gitea Actions results, and verify the staged application. Use for a staging release or a failed staging deployment.
+---
+
+# Deploy Staging
+
+Push the intended commit to `main` over the configured SSH remote. The `Validate and deploy staging` workflow builds the image, creates a database backup, applies migrations, and starts the app and scheduler.
+
+## Workflow
+
+1. Inspect `git status`, the staged diff, recent commits, and the current branch. Do not commit generated caches such as Python `__pycache__` directories.
+2. Run the relevant tests. Source changes require `npm run check` and `npm run build` before deployment.
+3. Commit only the intended files, then push with `git push git@git.jb.codes:jb/shd.build.git main`.
+4. Open Gitea Actions and inspect the workflow run for the pushed commit. Wait for both `validate` and `deploy` to succeed.
+5. If the deploy job fails, open the failed step output. Do not retry a database migration without reading its error and checking the generated SQL against the target schema.
+6. Verify `https://stage.shd.build/api/health` through the staging access layer or from the deployment host. Confirm the app container reports healthy and the scheduler runs.
+
+## Guardrails
+
+- The workflow owns the staging database lifecycle. Do not run `docker compose down --volumes`.
+- A failed migration stops the application. Fix and test the migration, commit the repair, and push a new commit. The workflow creates another backup before retrying.
+- Keep staging data intact during routine deployment. Use the explicit bootstrap or ISAC-import workflows for data replacement.
+- Report the workflow run, commit SHA, health result, and any backup path printed by the deployment logs.