opencode-skill-autodeploy

OpenCode deployment skill — enables OpenCode to deploy applications to Coolify or Dokploy through a structured workflow with human-in-the-loop approval.

Purpose

This skill provides OpenCode with deployment automation capabilities. It guides OpenCode through a structured deploy intent workflow: analyzing the codebase, generating a deploy.intent.yaml manifest, selecting the appropriate platform adapter, and executing the deployment with preflight checks and post-deploy verification.

Why It Exists

Deploying applications through AI assistants is powerful but risky. Without structured guidance, an AI might:

• Deploy to the wrong platform
• Skip health checks
• Leave secrets in manifests
• Misconfigure resource limits
• Ignore external dependencies

This skill enforces a disciplined approach: inspect → detect → manifest → platform selection → human approval → preflight checks → execute → post-deploy verification.

Key Features

• Structured workflow — 7-phase deployment process with clear checkpoints
• Human-in-the-loop — manifest presented for approval before any mutation
• Project detection — analyzes codebase to determine deployment type and platform
• Deploy intent manifest — portable deploy.intent.yaml format across all repos
• Preflight checks — validation before execution
• Post-deploy verification — health checks and log analysis
• Explicit guardrails — no secret values, no .env reading, explicit visibility defaults
• Templates — machine-readable manifest templates

Architecture Summary

┌─────────────────────────────────────────────────────────────┐
│  OPENCODE                                                   │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  opencode-skill-autodeploy                             │  │
│  │                                                        │  │
│  │  PHASE 1: INSPECT → PHASE 2: DETECT                    │  │
│  │  PHASE 3: MANIFEST → PHASE 4: HUMAN REVIEW              │  │
│  │  PHASE 5: EXECUTE → PHASE 6: VERIFY                    │  │
│  └───────────────────────────────────────────────────────┘  │
│                            │                                 │
│                            ▼                                 │
│  ┌──────────────┐   ┌──────────────────┐   ┌────────────┐  │
│  │ coolify-mcp  │   │  deploy.intent    │   │dokploy-mcp │  │
│  │              │◄──│    .yaml          │──►│            │  │
│  └──────────────┘   └──────────────────┘   └────────────┘  │
└─────────────────────────────────────────────────────────────┘

Skill Components

Component	Location	Purpose
INSTRUCTIONS.md	skill/	Phase-by-phase deployment instructions
WORKFLOW.md	skill/	Visual workflow and MCP tool sequences
GUARDRAILS.md	skill/	10 explicit operating rules
EXAMPLES.md	skill/	5 complete deployment examples
Templates	templates/	Machine-readable manifest templates

Supported Deployment Types

Kind	Build Strategy	Platform
SourceApp	Nixpacks	Coolify
DockerfileApp	Dockerfile	Either
ComposeApp	Docker Compose	Dokploy (prod), Coolify (dev)
StaticSite	Nixpacks	Coolify

Project Structure

opencode-skill-autodeploy/
├── skill/
│   ├── INSTRUCTIONS.md            # Phase-by-phase guide
│   ├── WORKFLOW.md                # Visual workflow + MCP sequences
│   ├── GUARDRAILS.md              # 10 explicit operating rules
│   ├── EXAMPLES.md                # 5 complete examples
│   └── README.md                  # Skill overview
├── templates/
│   ├── source-app.yaml          # Node/Python/Go source app template
│   ├── static-site.yaml         # Static site template
│   ├── dockerfile-app.yaml      # Custom Dockerfile template
│   ├── compose-app.yaml         # Docker Compose template
│   └── monorepo-app.yaml        # Monorepo sub-package template
├── docs/
│   ├── architecture.md
│   ├── decision-tree.md          # Platform selection guide
│   ├── failure-recovery.md       # Troubleshooting guide
│   └── manifest-spec.md          # deploy.intent.yaml spec
├── examples/                      # Additional examples
├── tests/                         # Unit tests
├── package.json
└── README.md

Installation

OpenCode Setup

Reference the skill in your OpenCode configuration:

skills:
  - name: autodeploy
    repo: opencode-skill-autodeploy
    path: skill/

Usage

Activation Commands

deploy <project>
deploy to coolify
deploy to dokploy
deploy compose stack

Deployment Flow

PHASE 1: INSPECT
  → Read project files (package.json, Dockerfile, compose, etc.)
  → Classify project type

PHASE 2: DETECT
  → Infer runtime, build command, start command, port
  → Identify secrets and external dependencies
  → Select target platform

PHASE 3: MANIFEST
  → Generate deploy.intent.yaml
  → Populate all required fields

PHASE 4: HUMAN REVIEW
  → Present manifest for approval
  → Await explicit "yes" or "approve"
  → Exception: CONFIRM=true skips interactive approval

PHASE 5: EXECUTE
  → Run preflight checks
  → Create application via MCP
  → Set environment variables
  → Assign domain (if configured)
  → Trigger deployment

PHASE 6: VERIFY
  → Poll deployment status
  → Check health endpoint
  → Analyze logs on failure
  → Report result

Guardrails (from GUARDRAILS.md)

ID	Rule	Behavior
G1	No secret values	Use ${PLACEHOLDER} only
G2	No .env reading	Only .env.example
G3	Human approval gate	Manifest must be approved
G4	Visibility default	Default to private
G5	No secret guessing	Ask human for values
G6	Preflight checks	Verify before mutate
G7	Production preservation	Show diff for existing apps
G8	Validate before execute	Validate manifest first
G9	External dependencies	Always warn
G10	Deterministic output	Structured format

Templates

Complete deploy.intent.yaml templates are in templates/. Each template is a realistic, production-ready manifest with all fields populated and documented with comments.

Template	Kind	Description
templates/source-app.yaml	SourceApp	Node.js API via nixpacks — JWT, PostgreSQL, health checks
templates/static-site.yaml	StaticSite	Vite + React static site — custom domains, env vars
templates/dockerfile-app.yaml	DockerfileApp	Custom Dockerfile — multi-stage, non-root user
templates/compose-app.yaml	ComposeApp	Multi-service stack — web, api, worker, db, redis
templates/monorepo-app.yaml	SourceApp	Monorepo sub-package — turbo/pnpm workspaces

All templates:

• Use ${PLACEHOLDER} syntax for secrets (never real values)
• Reference shared/examples/ for additional reference manifests
• Support both Coolify and Dokploy targets

Safety & Deployment Risks

Risk	Mitigation
Wrong platform selection	Decision tree guides correct platform choice
Missing secrets at runtime	All required secrets documented; placeholders used
External dependencies ignored	Warning section lists unmanaged services
Failed deployments	Post-deploy verification with health checks
Resource misconfiguration	Resource limits set per project type

Examples

See skill/EXAMPLES.md for complete examples:

1. Node.js single service → Coolify
2. Monorepo Dockerfile → Dokploy
3. Docker Compose stack → Dokploy
4. Failure: Build command missing
5. Failure: Platform switch for Docker-in-Docker

Limitations

• Requires MCP servers (coolify-mcp or dokploy-mcp) to be configured
• Human-in-the-loop approval cannot be bypassed without CONFIRM=true
• Platform adapter must match target platform
• No rollback automation (manual via platform dashboard)

Roadmap

• Add rollback automation via MCP
• Add support for Kubernetes deployments
• Add deployment cost estimation
• Add automatic secret rotation recommendations
• Add multi-region deployment support

Related Repositories

• coolify-mcp — MCP server for Coolify
• dokploy-mcp — MCP server for Dokploy
• claude-skill-autodeploy — Claude Code deployment skill
• codex-skill-autodeploy — Codex deployment skill

License

MIT License — see LICENSE file for details.