> ## Documentation Index
> Fetch the complete documentation index at: https://repost.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrations and Deploys
> Record schema changes as migrations, check them in CI, and deploy them to environments with safe rollback and fork detection.
Your schema changes over time, and your customers build against it, so changes are versioned the way database schemas are: recorded as migrations in your repo, reviewed in pull requests, checked in CI, and deployed deliberately. If you have used Prisma Migrate, the workflow is the same.
## Record a change
```bash theme={"languages":{"custom":["/languages/repost.json"]}}
repost schema migrate dev --name add_subtitle
```
`migrate dev` diffs your schema against the last migration. When something changed, it writes a timestamped snapshot under `repost/migrations/`, bumps the version of each affected event type, and regenerates your client. When nothing changed, it does nothing. The migration directory is committed, so every schema change shows up in `git diff` and code review.
Each migration records its parent and a checksum of its snapshot, which lets the CLI verify the whole history.
Removing event types requires confirmation. When a migration would drop event types, `migrate dev` lists them and asks for an explicit `y`. In CI it errors instead; pass `--accept-removals` to remove them deliberately.
## Merging branches
Two branches that each ran `migrate dev` merge cleanly in git, since migration directories are timestamp-prefixed and don't collide. After the merge the history briefly has two heads, called a fork. Commands that read migrations detect this and fail with the names of both directories rather than guessing.
To resolve a fork, run `repost schema migrate dev` once on the merged schema. It diffs against each parent, prints what each branch contributed, and writes a single reconciling migration that records both parents. Commit it.
## Check it in CI
```bash theme={"languages":{"custom":["/languages/repost.json"]}}
repost schema validate
repost schema migrate status
```
`migrate status` exits non-zero on a fork, on unmigrated changes (the schema is ahead of the recorded history), or on a hand-edited snapshot (checksum mismatch). It exits `0` when the history is clean. Run both commands on every pull request.
## Deploy
```bash theme={"languages":{"custom":["/languages/repost.json"]}}
repost schema migrate deploy
```
Deploying sends your migration history to the environment, which materializes the event-type registry from it and responds with the applied diff: created, updated, and archived event types. Re-deploying the same head does nothing.
Authentication comes from `REPOST_TOKEN`, an environment-scoped token with the `schema:deploy` scope, read from `repost/.env` before the process environment. `REPOST_API_URL` overrides the API host. Pass `--dry-run` to print the payload instead of sending it.
### The ancestry check
The server refuses any deploy whose head does not descend from what is already deployed, so production history can never be lost by accident.
| Situation | Result | Fix |
| ----------------------------------- | --------------------------------------- | ----------------------------------------------------- |
| Your head extends the deployed head | Applied. | — |
| Your checkout is behind | Refused (`client_behind`). | `git pull` the newer migrations and redeploy. |
| The histories diverged | Refused, with the reason. | Merge in git, reconcile with `migrate dev`, redeploy. |
| Another deploy raced yours | Refused, since the expected head moved. | Run the deploy again. |
Every deploy records which token performed it and whether it was forced.
### Forcing and rolling back
Some histories can never fast-forward: you squashed your migrations, re-initialized the directory, or restored from another repo. `repost schema migrate deploy --force` replaces the deployed history. Before doing anything it fetches the deployed head, prints exactly what will be replaced, and asks for confirmation (`--accept-replace` in CI).
Force is checked against the head you were shown. If another deploy moved it in the meantime, the server refuses instead of overwriting a head nobody reviewed. Forcing to an older, previously deployed checksum is the supported rollback path.
Archival is non-destructive. Event types removed by a deploy are archived, not deleted; they still accept publishes and still deliver. A wrong deploy or a rollback never drops in-flight traffic, and redeploying the correct head restores the registry.
## Development loops
```bash theme={"languages":{"custom":["/languages/repost.json"]}}
repost schema push
```
`push` sends the current schema without writing a migration, like Prisma's `db push`. It is intended for development and staging, and it is refused on environments that already have migration history, so it can never fork production. Pushing an unchanged schema does nothing.
## Importing from Svix
`repost schema import svix export.json` converts a Svix environment export into a `repost/` workspace: one catalog member and event binding per event type, a payload model per schema, and an initial migration that preserves the source's version history. Names are kept verbatim. Anything that cannot be represented is reported as an error listing every case, rather than being silently changed.
## Continue
Your events are live. Generate a client and publish.
Every `repost schema` command and flag.
Each deploy rebuilds your customer-facing event documentation.