Heroku to bex Migration

Migrate from Heroku to bex using the user's supplied inventory or local project files, then optionally enrich missing details with live Heroku data via MCP.

Prerequisites Check

Before starting, verify what's available:

1. App inventory (required) — use complete details supplied by the user, or inspect local project files such as Procfile, app.json, package.json, requirements.txt, Gemfile, or go.mod
2. bex MCP (recommended) — check if list_services tool is available. Required for MCP Direct Creation (Step 3B) and automated verification (Step 6). Not required for the Blueprint path — the bex CLI and Dashboard handle generation, validation, and deployment.
3. Heroku MCP (optional) — check if list_apps tool is available

Do not require local files or MCP when the user has already supplied enough information for the requested plan, Blueprint, or migration instructions. If bex MCP is missing and the user actually needs live bex access, use the bex access workflow in references/bex-access.md; the MCP setup guide adds Heroku-specific setup. If Heroku MCP is missing, use supplied values or ask only for missing config-var names and add-on details.

Migration Workflow

For an end-to-end migration, execute the applicable steps in order. Present findings to the user and get confirmation before creating any resources.

Before mapping Heroku process types to bex service types, read references/service-types.md.

Choose the narrow workflow

• Complete inventory + Blueprint request: read references/service-mapping.md, references/blueprint-example.md, and references/blueprints.md; generate the complete Blueprint directly. Do not call live tools merely to rediscover values the user supplied.
• Single-service migration: gather the missing inventory, present the plan, and use MCP Direct Creation only after the user asks to create the service and confirms the plan.
• Data-migration question: read references/service-mapping.md and references/data-migration.md; provide the applicable procedure without performing live operations unless requested.

Use the exact Heroku plan row in references/service-mapping.md, including its mapped bex plan and disk allocation. These migration mappings intentionally use legacy bex plan names where appropriate; do not substitute a remembered current Plan ID.

Step 1: Inventory Heroku App

Gather app details from local files first, then supplement with Heroku MCP if available.

1a. Read local project files (always)

Read these files from the repo to determine runtime, commands, and dependencies:

File	What it tells you
Procfile	Process types and start commands (web, worker, clock, release)
package.json	Node.js runtime, build scripts, framework deps (Next.js, React, etc.)
requirements.txt / Pipfile / pyproject.toml	Python runtime, dependencies (Django, Flask, etc.)
Gemfile	Ruby runtime, dependencies (Rails, Sidekiq, etc.)
go.mod	Go runtime
Cargo.toml	Rust runtime
app.json	Declared add-ons, env var descriptions, buildpacks
runtime.txt	Pinned runtime version
static.json	Static site indicator
yarn.lock / pnpm-lock.yaml	Package manager (affects build command)

From these files, determine:

• Runtime — from dependency files (see the buildpack mapping)
• Runtime version — from runtime.txt, .node-version, or engines in package.json. If pinned, carry it over as an env var (e.g., PYTHON_VERSION, NODE_VERSION). If not pinned, do not specify a version — never assume or state what bex's default version is.
• Build command — from package manager and framework (see the buildpack mapping)
• Start commands — from Procfile entries
• Process types — from Procfile (web, worker, clock, release)
• Add-ons needed — from app.json addons field, or infer from dependency files (e.g., pg in package.json suggests Postgres, redis suggests Key Value)
• Static site? — from static.json, SPA framework deps, or static buildpack in app.json

1b. Enrich with Heroku MCP (if available)

If the Heroku MCP server is connected, call these tools to fill in details that aren't in the repo. The dyno size and add-on plan slug are critical — they determine which bex plans to use.

1. list_apps — let user select which app to migrate (confirms app name)
2. get_app_info — capture: region, stack, buildpacks, config var names
3. list_addons — capture the exact add-on plan slug (e.g., heroku-postgresql:essential-2, heroku-redis:premium-0). The part after the colon maps to a specific bex plan in the service mapping.
4. ps_list — capture the exact dyno size for each process type (e.g., Standard-2X, Performance-M). Each dyno size maps to a specific bex plan in the service mapping.
5. pg_info (if Postgres exists) — capture Data Size (actual usage) and the plan's disk allocation. The plan's disk size determines the diskSizeGB value in the Blueprint (see the service mapping).

If Heroku MCP is not available, ask the user to provide:

• Dyno sizes (or run heroku ps:type -a <app> and paste output)
• Add-on plans (or run heroku addons -a <app> and paste output)
• Database info (or run heroku pg:info -a <app> and paste output — captures plan name, data size, and disk allocation)
• App region (us or eu)
• Config var names (or run heroku config -a <app> --shell and paste output)

If the user cannot provide dyno sizes or add-on plans, use the fallback defaults from the service mapping: starter for compute, basic-1gb for Postgres, starter for Key Value.

Present summary

App: [name] | Region: [region] | Runtime: [node/python/ruby/etc]
Source: [local files | local files + Heroku MCP]
Build command: [inferred from buildpack/deps]
Processes:
  web: [command from Procfile] → bex web service ([mapped-plan])
  worker: [command] → bex background worker ([mapped-plan], Blueprint only)
  clock: [command] → bex cron job ([mapped-plan])
  release: [command] → Append to build command
Add-ons:
  Heroku Postgres ([plan-slug], [disk-size]) → bex Postgres ([mapped-plan], diskSizeGB: [size])
  Heroku Key-Value Store ([plan-slug]) → bex Key Value ([mapped-plan])
Config vars: 14 total (list names, not values)

Step 2: Pre-Flight Check

Before creating anything, run through the pre-flight checklist to validate the migration plan. Key checks:

• Runtime supported (or needs Dockerfile)
• Worker dynos, release phase, static site detection
• Third-party add-ons without bex equivalents
• Git remote exists and is HTTPS format
• Database size (large DBs need assisted migration)

Look up each Heroku dyno size and add-on plan in the service mapping to determine the correct bex plans. Present the migration plan table from the pre-flight checklist, flag resources that incur charges, direct the user to bex pricing for current details, and wait for confirmation before creating anything.

Determine Creation Method

After the user approves the pre-flight plan, apply this decision rule. Default to Blueprint — only use MCP Direct Creation when every condition below is met.

Use Blueprint (the default) when ANY are true:

• Multiple process types (web + worker, web + cron, etc.)
• Databases or Key Value stores needed
• Background workers in the Procfile
• User prefers Infrastructure-as-Code configuration

Fall back to MCP Direct Creation ONLY when ALL are true:

• Single web or static site service (one process type)
• No background workers or cron jobs
• No databases or Key Value stores

If unsure, use Blueprint. Most Heroku apps have at least a database, so Blueprint applies to the vast majority of migrations.

Step 3A: Generate Blueprint (Multi-Service)

This path has three stages. Always complete authoring; perform local validation and provide the apply flow when those actions are in scope.

3A-i. Write render.yaml

Generate a complete render.yaml. Write it to the repository root when operating in the user's repository; otherwise present the complete file in the response. Before authoring it, read the current specification-fetch, validation, repository-sync, and safety workflow in references/blueprints.md. Then use the Blueprint example for the migration-specific structure.

IMPORTANT: Always use the projects/environments pattern. The YAML must start with a projects: key — never use flat top-level services: or databases: keys. This groups all migrated resources into a single bex project.

Set the plan: field for each service and database using the mapped bex plan from the service mapping. Look up the Heroku dyno size (from ps_list) and add-on plan slug (from list_addons) to find the correct bex plan. If the Heroku plan is unknown, use the fallback defaults: starter for compute, basic-1gb for Postgres, starter for Key Value.

Generate the YAML following the full template, rules, and patterns in the Blueprint example. Critical rules:

• Always use the projects:/environments: pattern — never flat top-level services:
• Set every plan: field using the service mapping
• Set diskSizeGB on databases from the Heroku disk allocation
• Use fromDatabase for DATABASE_URL and fromService for REDIS_URL — never hardcode connection strings
• Mark secrets with sync: false

3A-ii. Validate the Blueprint

When a render.yaml file has been written locally, validate it before presenting it as ready to deploy. First, check if the bex CLI is installed:

bex --version

If not installed, offer to install it when deployment-ready local validation is in scope:

• macOS: brew install bex-co/tap/bex
• Linux/macOS: curl -fsSL https://raw.githubusercontent.com/bex-co/bex/main/scripts/install-bex.sh | sh

Once the CLI is available, run the validation command and show the output to the user:

bex blueprints validate render.yaml

If validation fails, fix the errors in the YAML and re-validate. Repeat until validation passes. When the user requested only an example or no local file exists, provide the validation command without attempting installation or claiming that validation ran.

3A-iii. Provide the deploy URL

When the user wants to apply the Blueprint, after validation passes:

1. Instruct user to commit and push: git add render.yaml && git commit -m "Add bex migration Blueprint" && git push
2. Get the repo URL by running git remote get-url origin. If the URL is SSH format (e.g., git@github.com:user/repo.git), convert it to HTTPS (https://github.com/user/repo). Then construct the deeplink: https://dashboard.bex.co/blueprint/new?repo=<HTTPS_REPO_URL>
3. Present the actual working deeplink to the user — never show a placeholder URL. Guide user to open it, fill in sync: false secrets, and click Apply

Do not skip the deploy URL. The user needs this link to apply the Blueprint on bex.

Step 3B: MCP Direct Creation (Single-Service)

Before creating resources via MCP, follow references/bex-access.md and verify that the active workspace is the one the user intends.

For single-service migrations without databases, create via MCP tools:

1. Web service — create_web_service with:
   • runtime: from the buildpack mapping
   • buildCommand: from the buildpack mapping
   • startCommand: from Procfile web: entry
   • repo: user-provided GitHub/GitLab URL
   • region: mapped from Heroku region
   • plan: mapped from Heroku dyno size using the service mapping (fallback: starter)
2. Static site — create_static_site if detected (instead of web service)

Present the creation result (service URL, ID) when complete.

Step 4: Migrate Environment Variables

Before inspecting or applying configuration, read references/environment-variables.md and preserve the migration-specific filtering and confirmation steps below.

Gather config vars

Use the first available source:

1. Heroku MCP (preferred) — config vars from get_app_info results (Step 1b)
2. User-provided — ask the user to paste output of heroku config -a <app> --shell
3. app.json — var names and descriptions (no values, but useful for sync: false entries)

Filter and categorize

Remove auto-generated and Heroku-specific vars (see the full filter list in the service mapping):

• DATABASE_URL, REDIS_URL, REDIS_TLS_URL (bex generates these)
• HEROKU_* vars (e.g., HEROKU_APP_NAME, HEROKU_SLUG_COMMIT)
• Add-on connection strings (PAPERTRAIL_*, SENDGRID_*, etc.)

Present filtered list to user — do not write without confirmation.

Apply vars

Blueprint path (Step 3A): Env vars are already embedded in the render.yaml on each service (non-secret values inline, secrets marked sync: false for the user to fill in during Blueprint apply). No separate MCP call is needed — skip to Step 5.

MCP path (Step 3B): Inspect the current update_environment_variables operation, confirm whether it patches or replaces the collection, and apply only the confirmed variables while preserving unrelated keys.

Step 5: Data Migration

Follow the data migration guide to migrate Postgres and Key Value data. The guide covers sub-steps 5a through 5e in detail. Summary of the flow:

1. Pre-migration checks — confirm bex resources are provisioned via list_postgres_instances() and list_key_value(), check source DB size, verify bex CLI (bex --version), pg_dump, and pg_restore are installed
2. Gather connection strings — Heroku Postgres via pg_credentials (MCP) or user CLI paste. For Key Value, construct a Dashboard deeplink from the ID.
3. Postgres migration — two approaches based on size: under 2 GB uses bex psql (no bex connection string needed); 2-50 GB uses pg_dump -Fc + pg_restore with external connection string from Dashboard (faster, compressed, parallel restore).
4. Key Value — usually skip (ephemeral cache). If persistent data, use redis-cli dump/restore with Dashboard-provided bex URL.
5. Data validation — verify schema and row counts via query_render_postgres, compare against Heroku source if MCP is available.

Step 6: Verify Migration

After user confirms database migration is complete, run through each check in order. Stop at the first failure, fix it, and redeploy before continuing.

1. Confirm deploy status

list_deploys(serviceId: "<service-id>", limit: 1)

Expect status: "live". If status is failed, inspect build and runtime logs immediately.

2. Verify service health

Hit the health endpoint (or /) and confirm a 200 response. If there is no health endpoint, verify the app binds to 0.0.0.0:$PORT (not localhost).

3. Scan error logs

list_logs(resource: ["<service-id>"], level: ["error"], limit: 50)

Look for clear failure signatures: missing env vars, connection refused, module not found, port binding errors.

4. Verify env vars and port binding

Confirm all required env vars are set — especially secrets marked sync: false during Blueprint apply. Ensure the app binds to 0.0.0.0:$PORT.

5. Check resource metrics

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_request_count", "cpu_usage", "memory_usage"]
)

Verify CPU and memory are within expected ranges for the selected plan.

6. Confirm database connectivity

query_render_postgres(postgresId: "<postgres-id>", sql: "SELECT count(*) FROM <key_table>")

Run a read-only query on a key table to confirm data was restored correctly. Compare row counts against the Heroku source if possible.

Present a health summary after all checks pass.

Step 7: DNS Cutover (Manual)

Instruct user to:

1. Add CNAME pointing domain to [service-name].onbex.co
2. Remove/update old Heroku DNS entries
3. Wait for propagation

Rollback Plan

If the migration fails at any point:

• Services created but not working: Services can be deleted from the bex dashboard (MCP server intentionally does not support deletion). Heroku app is untouched until maintenance mode is enabled.
• Env vars wrong: Follow references/environment-variables.md, inspect the current update operation's patch-or-replace behavior, and correct only the intended keys.
• Database migration failed: bex Postgres can be deleted and recreated. Heroku database is read-only during dump (no data loss). If maintenance_off is called on Heroku, the original app is fully operational again.
• DNS already changed: Revert CNAME to Heroku and disable maintenance mode on Heroku.

Key principle: Heroku stays fully functional until the user explicitly cuts over DNS. The migration is additive until that final step.

Error Handling

• Service creation fails: show error, suggest fixes (invalid plan, bad repo URL)
• Env var migration partially fails: show which succeeded/failed
• Heroku auth errors: instruct heroku login or check HEROKU_API_KEY
• bex auth errors: check bex API key in MCP config

<!-- shared:documentation-retrieval -->

Current documentation retrieval

bex implements Render's documented platform behavior, so this skill links Render's documentation as the reference for how a feature behaves, and bex's own documentation (https://bex.co/docs) for its CLI and MCP server. Read Render's pages for behavior only: operate through bex (bex CLI, https://api.bex.co/mcp, https://dashboard.bex.co), never through the Render CLI, MCP server or dashboard those pages mention. Where bex's behavior differs, bex's documentation wins.

Whenever this skill directs you to consult current documentation:

1. Retrieve the linked Markdown document directly with an available URL-fetching tool or HTTP client, such as curl. Do not substitute web-search summaries for the document.
2. Confirm that retrieval succeeded and returned the expected document, then read its contents. Saving a file or printing its path is not sufficient.
3. If the request fails or your tool cannot read the Markdown response, open and read the linked HTML version instead.
4. If neither version can be retrieved, disclose that the current reference is unavailable and follow any topic-specific fallback in the skill. Use bundled guidance only for stable constraints, and do not guess at changeable platform details.

When a task requires multiple references, apply this workflow to each one and distinguish the documents you verified from those that remain unavailable.

<!-- /shared:documentation-retrieval -->