---
name: dokploy-deploy
version: 1.0.0
applies_to: [devops]
risk: 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