app-platform-migration
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.
How do I install this agent skill?
npx skills add https://github.com/digitalocean-labs/do-app-platform-skills --skill app-platform-migrationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates the migration of applications from various cloud platforms to DigitalOcean App Platform by analyzing repository configurations and generating deployment specifications. No security issues or malicious patterns were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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:
- Analyzes thoroughly before proposing changes
- Maps what it can with confidence
- Acknowledges gaps clearly and specifically
- Asks before proceeding when uncertain
- 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
| Platform | Config Files | Support Level |
|---|---|---|
| Heroku | Procfile, app.json, heroku.yml | Full (deep chapter) |
| Docker Compose | docker-compose.yml | Full |
| Render | render.yaml | Full |
| Railway | railway.json, railway.toml | Full |
| Fly.io | fly.toml | Full |
| AWS ECS | Task Definition JSON | Partial |
| AWS App Runner | apprunner.yaml | Partial |
| Generic Docker | Dockerfile only | Full |
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)
| Heroku | App Platform |
|---|---|
web process | services |
worker process | workers |
release phase | jobs (PRE_DEPLOY) |
heroku-postgresql | Managed Postgres |
heroku-redis | Managed Valkey |
| Config Vars | GitHub Secrets |
| Pipelines | GitHub Actions |
| Review Apps | Preview environments |
| Heroku Scheduler | jobs (CRON_TRIGGER) |
Full mapping: See heroku-mapping.md
Quick Mapping Reference
Docker Compose
| Docker Compose | App Platform |
|---|---|
services.<name>.ports | services |
services.<name> (no ports) | workers |
services.postgres | Managed Postgres |
services.redis | Managed Valkey |
volumes | Spaces (no persistent volumes) |
Full mapping tables: See platform-mappings.md
Unmappable Items (Quick Reference)
| Source | Issue | Options |
|---|---|---|
| CloudFront CDN | No DO CDN | External CDN (Cloudflare) or skip |
| AWS Secrets Manager | Different model | GitHub Secrets |
| Persistent volumes | Not supported | Spaces for files, managed DB for data |
| ARM containers | AMD64 only | Rebuild for AMD64 |
Full list: See platform-mappings.md
Output Artifacts
| File | Purpose |
|---|---|
.do/app.yaml | App Platform specification |
.do/deploy.template.yaml | Deploy to DO button |
MIGRATION.md | Migration checklist and status |
.env.example | Environment variable template |
App spec templates: See app-spec-generation.md
Scripts
| Script | Purpose |
|---|---|
scripts/detect_platform.py | Detect source platform from files |
scripts/analyze_architecture.py | Analyze application architecture |
scripts/generate_app_spec.py | Generate .do/app.yaml |
scripts/generate_checklist.py | Generate migration checklist |
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)
| Issue | Cause | Fix |
|---|---|---|
| App spec validation fails | Invalid YAML | Check indentation, doctl apps spec validate |
| Database connection fails | Wrong URL format | Use ${db.DATABASE_URL} binding |
| Build fails | Missing dependencies | Check Dockerfile build deps |
| Port binding fails | Wrong PORT handling | Bind to $PORT or 0.0.0.0:8080 |
| Health check fails | Wrong path | Verify /health endpoint exists |
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/digitalocean-labs/do-app-platform-skills/app-platform-migration">View app-platform-migration on skillZs</a>