Deployment

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