AOS/agency-agents/skills/dokploy-deploy/SKILL.md

name, version, applies_to, risk

name	version	applies_to	risk
dokploy-deploy	1.0.0	devops	high

Dokploy Production Deploy

When to use

When a task requires deploying a service to a production Dokploy environment (or a Traefik routing/TLS change treated as a deploy). Staging restarts do not use this skill — they are within the devops agent's own authority.

Steps

1. Confirm branch builds green. Read CI status on the source branch via github:read_pr / github:read_repo. Lint, unit, and integration tests must pass on the exact commit being deployed. Red CI → blocked.
2. Confirm no live DB migration pending. Check the project's migration directory and the AOS task list. If a db:migrate_live is pending or in flight on the target env, stop — deploy and migration must not run concurrently. Return blocked with the open question.
3. Verify a fresh backup exists. Use backup (skill) to confirm a backup of the affected service + database exists, timestamped within 24 hours. No backup, no deploy → blocked. Record the backup ref for the payload.
4. Capture pre-deploy state. dokploy:read_status and dns:read for the affected domain(s). Record before/after as a note on the task.
5. Compose the deploy runbook (inline on the task): target env, service name, image/tag, source commit + branch, expected duration, blast radius (which clients/services are affected), maintenance-window need, rollback steps (image tag to revert to, any DB revert), verification queries.
6. Create an ApprovalRequest (schemas/approval.json): action: production_deploy, risk: high, rationale (1–3 sentences on why now), diff_summary (service, env, commit short-sha, rollback tag), payload: { env, service, image, commit, backup_ref, rollback_ref, blast_radius, expected_duration_min }, optional expires_at for a time-bounded window.
7. Pause. The policy crate will not execute dokploy:deploy_production without an approved matching approval. The human approves; you do not.
8. On approval, the deploy executes (via the policy crate, not your direct tool call). Monitor via dokploy:read_status until the service reports healthy.
9. Verify the health endpoint. Issue an authenticated GET against the service's health/readiness URL. Expect 2xx and the documented health body. Any other status → trigger rollback per the runbook and escalate.
10. Smoke-test the golden path. Execute the project's documented smoke test (one happy-path transaction, one auth flow, one read). Failures → rollback, then escalate.
11. Log to AOS. Write a note on the task with: deploy timestamp, commit, image, approver, backup ref, health-check result, smoke-test result, rollback status (if any). No silent infra drift.

Inputs

• A task with task_id (AOS-NNNN), target environment, service, and commit.
• A green CI run on that commit.
• A fresh backup ref for the affected service + DB.
• The project's smoke-test runbook.

Outputs

An AgentDeliverable (schemas/deliverable.json) with:

• status: needs_approval (waiting) | done (post-deploy verified) | blocked (pre-conditions failed) | failed (post-deploy checks failed)
• deliverables[]: deploy runbook (inline), pre/post status snapshots, health-check result, smoke-test result, AOS note ref.
• risks[]: blast radius, rollback risk, DNS propagation risk, maintenance window, any condition that was borderline (e.g. backup older than 24h).
• cost: tokens only (no external spend; approvals handle spend).

Guard rails / compliance

• NEVER deploy without an approved ApprovalRequest of action production_deploy. The policy crate enforces this; do not attempt to bypass it.
• NEVER deploy during a pending or in-flight DB migration.
• ALWAYS verify the health endpoint and run the golden-path smoke test post-deploy. Failures trigger rollback, not "we'll watch it".
• ALWAYS have a verified backup before requesting the deploy.
• Traefik label/router/middleware/TLS changes are deploys — same flow.
• DB migrations on live data are a separate db_migration_live approval; they are never bundled into a production deploy.
• Staging restarts are not deploys; they are within devops authority but must still be logged as a note.

References

• schemas/approval.json — production_deploy action
• schemas/deliverable.json — return envelope
• policies/autonomy.md — production deploys always human-approved
• policies/tool-risk.md — dokploy:deploy_production is risk: high
• agents/software/devops.md — operating rules
• backup skill — backup verification