---
name: deploy-to-ghaym
description: Deploy a repository to Ghaym Cloud. Use when the user asks to deploy, ship or release this project to Ghaym, to set it up for Ghaym, to find out why a Ghaym deploy failed, or to read an error the Ghaym API returned. Covers the four checks before a deploy, the deploy itself, and how to read an API error, each with a link to the docs page behind it.
---

# Deploy to Ghaym Cloud

Save as `.claude/skills/deploy-to-ghaym/SKILL.md` in the repository, or under `~/.claude/skills/`
to have it everywhere. Canonical version: https://ghaym.me/integrations/ghaym-skill.md

Each step links the page of the Ghaym Cloud docs that explains it; read that page before acting
on the step. To learn every command and flag in one call:

```sh
ghaym help all --json
```

## Before you start

Sign-up needs a person, and deploying opens once Ghaym approves the account. If the user has no account, say
so and stop.
[Set up a coding agent](https://ghaym.me/en/docs/agents)

Use the CLI, not hand-written API calls. Never ask the user to paste a key into the conversation;
if `ghaym whoami` fails, ask them to run `ghaym login` in their own terminal.
[Set up a coding agent](https://ghaym.me/en/docs/agents)

## Check four things before deploying

1. **The app listens on every address, on the port Ghaym sets.** It binds to `0.0.0.0`, not to
   localhost, and reads the port from `PORT`. An app bound to localhost fails the readiness check.
   [Builds and deploys](https://ghaym.me/en/docs/builds)
2. **The repository builds.** Most languages are detected on their own; anything else needs a
   `Dockerfile`. [Builds and deploys](https://ghaym.me/en/docs/builds#how-the-image-is-built)
3. **No secret is in the repository.** No `.env` is committed and no key is about to be. Values
   belong in Ghaym, set with `ghaym cloud vars set`.
   [Set variables and secrets](https://ghaym.me/en/docs/variables)
4. **The branch you push is the one the service tracks.** Confirm it with the user; don't assume
   `main`. [Deploy from GitHub](https://ghaym.me/en/docs/deploy-from-github)

## Deploy

1. If the project doesn't exist yet, `ghaym cloud git install` prints the link that installs the
   Ghaym GitHub App, `ghaym cloud projects create --name <name>` creates the project, and
   `ghaym cloud services create --project <project> --type git --repo <owner/name> --size <size> --site <slug>`
   creates the service and starts its first deploy. `ghaym cloud regions list`
   names the sites. [Deploy your first service](https://ghaym.me/en/docs/getting-started)
2. Push. A push to the branch a service tracks builds and deploys it, in every environment that
   tracks that branch.

   ```sh
   git push origin <branch>
   ```

   [Deploy from GitHub](https://ghaym.me/en/docs/deploy-from-github)

3. Read the build log with `ghaym cloud deployments logs <id>`. A successful push only means Git
   accepted the commit; the deploy has worked only when the build log says so.
   [Builds and deploys](https://ghaym.me/en/docs/builds)

To try a change away from production, run
`ghaym cloud environments create --project <project> --name <name> --branch <branch>`, then push
to that branch. [Deploy a branch to its own environment](https://ghaym.me/en/docs/branch-environments)

To undo a bad deploy, run `ghaym cloud deployments rollback <id>`. Ghaym puts that deploy's image
live again without a build. [Roll back a deploy](https://ghaym.me/en/docs/rollback)

Every change is staged: variables, build settings, size, replicas, routing and access
move only with `ghaym cloud changes apply`, or `--apply` on the same call.
Applying a variable, a bucket connection, the branch or a build setting deploys the service.
[Staged changes](https://ghaym.me/en/docs/staged-changes)

Try a change first: every command that changes something takes `--dry-run`, and then changes
nothing. [CLI reference](https://ghaym.me/en/docs/cli)

A command that needs approval exits with `6` and an approval id. Run
`ghaym cloud approvals wait <id>` instead of retrying.
[Supervise a coding agent](https://ghaym.me/en/docs/agent-approvals)

## Read an API error

Every error is a JSON document in RFC 9457 format. With `--json`, the CLI puts this document under
`error`. [API errors](https://ghaym.me/en/docs/errors)

- `type`: the error's name, such as `not-found`. Branch on it, not on the text.
- `title`: a short English title for the type.
- `status`: the HTTP status.
- `detail`: what went wrong with this call, for a person to read. Show it to the user.
- `docs`: the link to the type's page, with what causes the error and how to fix the call. Follow
  it before retrying.

A call to the API signs in with an access token traded for the key.
[API keys and scopes](https://ghaym.me/en/docs/api-keys)

## Cost

- Prices depend on the site. Read them with `ghaym cloud regions sizes <region>`.
  [Limits and prices](https://ghaym.me/en/docs/limits-and-prices)
- Polling keeps a service awake. Services outside production sleep when idle, and
  compute is charged only while a service is awake. [Sleep and wake](https://ghaym.me/en/docs/sleep)
