deploy-anonymous

Files (1)

• SKILL.md

SKILL.md (first lines)

# Deploy to Heroku (Anonymous Preview)

## Step 1 — Verify prerequisites

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/preflight.py --quick --json
```

Gate on: `git: true`. Heroku CLI login is not required for the MCP deploy path.
If git check fails, surface the preflight error and stop.

## Step 2 — Verify scaffolded app

**Read `.heroku-plugin-scaffold.json` first.** You need `stack`, `addons`, and `secret_env_vars` in later steps, and `stack` determines which other files are required.

Then verify the target directory contains:
- `project.toml` (CNB buildpack specification — required for all stacks)
- `.git/` directory (git repo initialized with at least one commit)
- `Procfile` with `web:` process — **required for all stacks except `website`**. The `heroku/static-web-server` buildpack provides the web process — **do not create a Procfile** for a website stack app.

If any required file is missing, suggest running `/heroku-plugin:scaffold-app` first.

## Step 3 — Create anonymous session

```
Tool: create_anonymous_session
Input: {}
Output: { conversation_id }
```

Store `conversation_id` — thread it into every subsequent MCP call.

## Step 4 — Create preview app

```
Tool: create_preview_app
Input: { conversation_id }
Output: { app_uuid, web_url, git_url, git_credentials: { token, expires_at }, mcp_credentials }
```

- Store `app_uuid` — required for all remaining MCP calls
- Store `git_url` and `git_credentials.token` — used in Step 7
- Do **not** surface `web_url` from this step — it is the raw `*.herokuapp.com` address, not the link to give the user
- `git_credentials` expire quickly (~5 min) — the push (Step 7) must land inside that window. Everything between here and the push is kept to *fast* calls only (Steps 5–6); the *slow* work (addon readiness, build) is deferred to Step 8, after the push, so it never eats the credential window

> **Steps 5–8 ordering — the credential clock.** The push (Step 7) is the critical path: it
> must happen before the Step 4 token lapses (~5 min). So Steps 5 and 6 are *fast* calls only —
> set secrets, then fire addon creation without waiting. The *slow* work (addon readiness + the
> build) is deferred to Step 8 and polled concurrently, **after** the push. Never let addon
> readiness polling block the push.

## Step 5 — Set secrets [CLI — known gap]

Read `secret_env_vars` from `.heroku-plugin-scaffold.json`. **If empty, skip this step entirely** — most stacks (node, python/fastapi, go, website) have no secrets and never reach here.

If non-empty (Django, Rails): the mcp-portal has no `set_config_vars` tool. The Heroku CLI is required for this step. If the user does not have the CLI installed or is not logged in, surface:

```
⚠ This app needs secret config vars set before the build, but the mcp-portal does not
  support setting config vars. The Heroku CLI is required for this step.

  Install: https://devcenter.heroku.com/articles/heroku-cli
  Then run: heroku login

  Let me know when you're ready and I'll continue.
```

Wait for confirmation, then set each secret before the push:

```bash
heroku config:set <NAME>=$(python3 -c 'import secrets; print(secrets.token_hex(32))') --app <app_uuid>
```

The `app_uuid` works as the `--app` identifier. Common values: `DJANGO_SECRET_KEY` (Django), `RAILS_MASTER_KEY` (Rails).

## Step 6 — Kick off addon provisioning (do not wait)

Read the `addons` array from `.heroku-plugin-scaffold.json`. If empty, skip this step.

For each addon slug, **fire** the provision — call `create_addon` and move straight on. Do
**not** poll `get_addon_status` here; readiness is polled in Step 8, concurrently with the
build. `create_addon` returns quickly and only *starts* provisioning, so firing it before the
push lets provisioning overlap the build — maximizing the chance the addon is ready before any
release phase runs.

```
Tool: create_addon
Input: { app_uuid, service }
Output: { id, app, plan, state, config_vars }
```

Store each `id` — Step 8 polls it for readiness as `addon_id`.

**Service slug mapping** (pass exactly these values as `service`):
| `.heroku-plugin-scaffold.json` slug | MCP `service` value |
|---|---|
| `heroku-postgresql` | `heroku-postgresql` |
| `heroku-redis` | `heroku-redis` |

If `create_addon` returns `isError: true`, surface the error and ask the user whether to
continue without the addon or stop.

## Step 7 — Push source

Push **immediately** after Step 6 — this is the critical path against the credential clock; do
not wait on addon readiness (that is Step 8).

**Use the git push command from the `create_preview_app` tool description exactly — including
any push options it specifies (e.g. `-o heroku.action=async`).** Do not substitute or simplify
the command. The tool description is the authoritative source; this skill does not override it.

The push output is unstructured text from `git push` — there is no structured `build_id` field.
Capture the full stdout and parse it: the build id appears in the `*** Images (...)` block near
the end of the output as `builds:<uuid>` — regex `builds:([0-9a-f-]{36})`. `build_id` is
optional — `get_deployment_status` defaults to the latest build for the app when omitted.

If the push fails with a credential error, the token from Step 4 has likely lapsed (~5 min
after `create_preview_app`). Surface the full output and stop — re-running the deploy mints a
fresh session and app.

From heroku/heroku-claude-plugin, Apache-2.0.

More from heroku/heroku-claude-plugin