app-platform-migration

name: app-platform-migration version: 1.0.0 min_doctl_version: "1.82.0" description: Migrate applications from Heroku, AWS, Render, Railway, Fly.io, or Docker Compose to DigitalOcean App Platform. Use when converting existing apps, mapping services, refactoring platform-specific code, or creating app specs from other platform configurations. related_skills: [designer, postgres, managed-db-services, networking, deployment] deprecated: false

App Platform Migration Skill

Migrate existing applications to DigitalOcean App Platform with honest capability assessment.

Philosophy

This skill is an honest partner, not a magic wand. It:

1. Analyzes thoroughly before proposing changes
2. Maps what it can with confidence
3. Acknowledges gaps clearly and specifically
4. Asks before proceeding when uncertain
5. Never guesses or ignores incompatibilities

Tip: For complex multi-step migrations, use the planner skill first. For all available skills, see root SKILL.md.

Quick Decision

What's your source platform?
├── Heroku (Procfile, app.json, heroku.yml) → See Heroku Deep Chapter below
├── Docker Compose → See Quick Start below
├── Render/Railway/Fly.io → See Quick Start below
├── AWS ECS/App Runner → Complex migration, see reference
└── Just Dockerfile → See Quick Start below

Supported Platforms

Migration Workflow

Phase 1: DISCOVERY
├── Clone/access repository
├── Detect source platform
├── Analyze architecture
└── Inventory all services

Phase 2: MAPPING
├── Map services → App Platform components
├── Map databases → Managed databases
├── Map storage → Spaces
├── Map secrets → GitHub Secrets
└── Identify unmappable items → REPORT TO USER

Phase 3: REFACTORING
├── Create target branch(es)
├── Update environment variables
├── Remove platform-specific code
├── Update Dockerfile if needed
└── Generate app spec

Phase 4: VALIDATION
├── Validate: doctl apps spec validate
├── Review changes with user
└── Generate migration checklist

Phase 5: HANDOFF
├── Push branches to repo
├── Provide manual steps checklist
└── Suggest deployment skill

Quick Start

Basic Migration

# User provides repo URL
"Migrate this app to App Platform: https://github.com/myorg/myapp"

# AI will:
# 1. Clone and analyze
# 2. Detect platform
# 3. Present mapping proposal
# 4. Ask for approval
# 5. Create branch with refactored code + app spec

With Branch Specification

"Migrate my Heroku app. Put test config in 'migrate/test', prod in 'migrate/prod'"

Full workflows: See workflow-examples.md

Heroku Migration (Deep Chapter)

For Heroku-specific migrations, a comprehensive chapter is available with deep knowledge of Procfile, app.json, heroku.yml, buildpacks, pipelines, add-ons, and CLI mapping.

Start here: Read heroku-overview.md to determine the migration mode (Q&A, Guided, or Auto-Migrate), then follow the routing to:

• heroku-concepts.md — Heroku config file schemas, CLI commands, buildpack detection, pipeline structure
• heroku-mapping.md — Component types, build config, env vars, instance sizes, networking, regions
• heroku-addons.md — Add-on detection from app.json, DO managed service equivalents, external alternatives
• heroku-workflows.md — Step-by-step procedures for Q&A, Guided, and Auto-Migrate modes

Quick Mapping (Heroku)

Full mapping: See heroku-mapping.md

Quick Mapping Reference

Docker Compose

Full mapping tables: See platform-mappings.md

Unmappable Items (Quick Reference)

Full list: See platform-mappings.md

Output Artifacts

App spec templates: See app-spec-generation.md

Scripts

Reference Files

Heroku (Deep Chapter)

• heroku-overview.md - Entry point: read first for any Heroku migration
• heroku-concepts.md - Procfile, app.json, heroku.yml, pipelines, CLI
• heroku-mapping.md - Deep Heroku → App Platform feature mapping
• heroku-addons.md - Add-on ecosystem mapping (Postgres, Redis, etc.)
• heroku-workflows.md - Migration workflows: Q&A, Guided, Auto-Migrate

General

• platform-mappings.md - All platform detection, mapping tables, gotchas
• code-refactoring.md - Env var updates, S3/Valkey migration, data migration
• workflow-examples.md - Docker Compose, AWS ECS walkthroughs
• app-spec-generation.md - Test/prod spec templates, defaults

Common Issues (Quick Fixes)

Full troubleshooting: See code-refactoring.md

Integration with Other Skills

• → deployment: GitHub Actions workflow after migration
• → postgres: Complex database setup, schema isolation
• → devcontainers: Local dev environment post-migration
• → troubleshooting: Debug container for migration issues

Documentation Links

• App Spec Reference
• Heroku Migration Guide
• Deploy to DO Button