Setup guide

Backs `doctl account get` / GET /v2/account, the skill's first-step auth check before any billable action.

↳ Cannot be narrowed further; it is already read-only and exposes only team email, status, and droplet limit.

Lists apps, reads the live spec for the .do/app.live.yaml baseline, lists deployments to record the last known-good ID, streams build/deploy/run logs, and calls POST /v2/apps/propose for cost.

↳ For an audit-only or cost-review run, grant app:read plus account:read and nothing else - proposing a spec and reading app_cost needs no write scope.

Creates a new app from .do/app.yaml (`doctl apps create --spec`).

↳ Omit entirely when the skill only maintains an existing app; app:update alone is enough to deploy changes.

Applies spec changes, triggers create-deployment after secret rotation, assigns alert destinations, and performs rollback / rollback commit / rollback revert.

↳ No narrower per-app scope exists on DigitalOcean PATs; isolate blast radius by putting production in its own team with its own token instead.

Destroys abandoned preview apps found during the zombie-spend sweep.

↳ Leave this scope off for production tokens - the skill can report deletion candidates and let a human run the delete.

Lists clusters to confirm engine, version, node size, and datacenter colocation, and reads connection-pool URIs and existing firewall rules.

↳ Sufficient on its own for the connection-sizing and colocation checks.

Creates the Managed PostgreSQL/MySQL/Valkey cluster and the transaction-mode connection pool used by the app.

↳ Skip when the cluster already exists and is merely being attached via `cluster_name` in the app spec.

Appends the `app:<app-uuid>` trusted-source firewall rule that locks the cluster to this app, and resizes or reconfigures pools.

↳ Required for the firewall step; there is no separate firewall-only scope.

Creates the DigitalOcean-hosted zone and the A/ALIAS/CNAME records that back a `type: PRIMARY` domain in the app spec so Let's Encrypt can validate.

↳ Not needed when DNS is external - use `type: ALIAS`/CNAME at the registrar and drop this scope.

Verifies the records DigitalOcean expects actually resolve before certificate issuance and the DOMAIN_FAILED alert fires.

↳ Read-only; safe to grant alongside domain:create.

Resolves `registry.digitalocean.com/<registry>/<image>:<tag>` sources when the component deploys a prebuilt image instead of building from Git.

↳ Omit for buildpack or Dockerfile-from-Git deployments, which never touch DOCR.

Cause: DIGITALOCEAN_ACCESS_TOKEN is unset, truncated, expired, or was revoked; or doctl is using a stale context from a previous `doctl auth init`.

Fix: Re-export the full `dop_v1_...` value (71 chars, no trailing newline), or run `doctl auth list` and `doctl auth switch --context <name>`. Expired tokens cannot be renewed - generate a new one at cloud.digitalocean.com/account/api/tokens.

Cause: The token was created with Custom Scopes that omit the scope this call needs (typically app:update, database:update, or domain:create), or the caller is a Biller-only team member.

Fix: Scopes are fixed at creation. Generate a replacement token with the missing scope ticked, or ask a team Owner to raise your role. Confirm which call failed by re-running it with `doctl ... --verbose`.

Cause: More than 5,000 requests per hour (or 250 burst) against api.digitalocean.com from this token - usually a tight `doctl apps logs --follow` loop or a polling script.

Fix: Back off and read RateLimit-Remaining / RateLimit-Reset from the response headers; replace polling with `doctl apps update --wait` / `doctl apps create-deployment --wait`, which stream server-side.

Cause: Cloud Native Buildpacks could not identify the runtime - wrong `source_dir`, a missing package.json/requirements.txt/go.mod at that path, or an `environment_slug` that does not match the repo layout.

Fix: Set `source_dir` to the subdirectory that actually contains the manifest, pin `environment_slug` explicitly, or switch the component to `dockerfile_path`. Inspect with `doctl apps logs <app-id> <component> --type build --tail 200`.

Cause: The container started but the health check never returned 200 - almost always a service bound to 127.0.0.1 instead of 0.0.0.0, an `http_port` that does not match the injected `PORT`, or `initial_delay_seconds` shorter than real cold-start.

Fix: Bind `0.0.0.0:$PORT`, make `http_port` match, raise `initial_delay_seconds` above measured boot time, and keep `/healthz` free of database calls. Confirm with `doctl apps logs <app-id> <component> --type run_restarted`.

Cause: instance_count x per-process client pool exceeded the Managed PostgreSQL backend ceiling (roughly 25 x RAM_GB - 3, so about 22 on a 1 GB node).

Fix: Point DATABASE_URL at a transaction-mode connection pool (`doctl databases pool create ... --mode transaction --size 20`) and cap the application-side pool, instead of upsizing the cluster to buy connections.

Cause: The client disabled TLS or a hand-built connection string dropped `sslmode=require`; DigitalOcean Managed Databases refuse plaintext connections.

Fix: Use the bindable `${db.DATABASE_URL}` (it already carries `sslmode=require`) rather than assembling a URL from host/port/user, and do not set `sslmode=disable` in the client.

Cause: The cluster's trusted sources do not include this app, so the connection is dropped before the TLS handshake - IP allowlists never work here because App Platform egresses from shared ranges.

Fix: `doctl databases firewalls append <cluster-id> --rule app:<app-uuid>` (or the `digitalocean_database_firewall` rule with `type = "app"`), then verify with `doctl databases firewalls list <cluster-id>`.