name: deployment
version: 1.0.0
min_doctl_version: "1.82.0"
description: Deploy applications to DigitalOcean App Platform via GitHub Actions with proper environment management and secrets handling. Use when setting up CI/CD pipelines, configuring staging/production environments, managing deployment secrets, or creating GitHub Actions workflows.
related_skills: [designer, troubleshooting]
deprecated: false

Deployment Skill

Deploy to App Platform using GitHub Actions and the app_action workflow.

Philosophy: PUSH Mode Deployment

This skill focuses on PUSH mode — where you define infrastructure as code and GitHub Actions drives deployment.

PULL MODE (Console-driven) — NOT covered by this skill
• Go to DigitalOcean Console → Create App → Point to GitHub
• App Platform auto-generates app spec
• Good for: Quick starts, manual one-offs

PUSH MODE (CLI/Actions-driven) — THIS SKILL
• Define app spec in repo (.do/app.yaml)
• Use GitHub Actions + app_action to deploy
• Good for: CI/CD, automation, GitOps, multi-environment

Tip: For complex projects, consider the planner skill for staged approaches. See root SKILL.md for all skills.

Quick Decision

Using GitHub Actions? (RECOMMENDED)
├── YES → Use digitalocean/app_action/deploy@v2
│         • Handles spec updates AND code deployments
│         • Manages app creation if doesn't exist
│         • Supports PR previews
│
└── NO (Manual/Scripting)
    ├── Spec changed? → doctl apps update --spec
    └── Code only? → doctl apps create-deployment

Quick Start: Environment Setup

# 1. Create DigitalOcean projects
doctl projects create --name "myapp-staging" --environment "Staging"
doctl projects create --name "myapp-production" --environment "Production"

# 2. Create GitHub environments
gh api --method PUT repos/:owner/:repo/environments/staging
gh api --method PUT repos/:owner/:repo/environments/production

# 3. Set secrets per environment (user fills in values)
gh secret set DIGITALOCEAN_ACCESS_TOKEN --env staging
gh secret set DIGITALOCEAN_ACCESS_TOKEN --env production
gh variable set DO_PROJECT_ID --env staging --body "PROJECT_ID"
gh variable set DO_PROJECT_ID --env production --body "PROJECT_ID"

Full setup guide: See initial-setup.md

Quick Start: Basic Workflow

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: digitalocean/app_action/deploy@v2
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        with:
          token: ${{ secrets.DIGITALOCEAN_ACCESS_TOKEN }}
          project_id: ${{ vars.DO_PROJECT_ID }}

All workflow templates: See workflow-templates.md

Workflow Selection

Quick Start: Debug Container

For complex apps with multiple integrations, deploy a debug container first:

# Add to .do/app.yaml temporarily
workers:
  - name: debug
    image:
      registry_type: GHCR
      registry: ghcr.io
      repository: bikramkgupta/do-app-debug-container-python
      tag: latest
    instance_size_slug: apps-s-1vcpu-2gb
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

# Connect and verify
doctl apps console $APP_ID debug
./diagnose.sh

Full guide: See debug-container-deployment.md

Quick Command Reference

Full reference: See command-reference.md

Reference Files

Quick Troubleshooting

Opinionated Defaults

Integration with Other Skills

• ← designer: Creates .do/app.yaml that deployment consumes
• ← postgres: Handles database setup, stores DATABASE_URL in GitHub Secrets
• → troubleshooting: Debug deployment failures
• ← devcontainers: Ensure local dev matches production

Production Checklist

• [ ] DO Projects created with environment tags
• [ ] GitHub environments created (staging, production)
• [ ] DIGITALOCEAN_ACCESS_TOKEN secret set per environment
• [ ] DO_PROJECT_ID variable set per environment
• [ ] .do/app.yaml with deploy_on_push: false
• [ ] .github/workflows/deploy.yml created
• [ ] Production protection rules enabled
• [ ] Staging deployment tested
• [ ] Production deployment tested

Documentation Links

• app_action GitHub Repository
• App Platform Docs
• App Spec Reference
• GitHub Environments Docs