Trigger deployments and roll back on Meridian

Every change you ship to an environment goes through a deployment. Meridian tracks the full lifecycle of each deployment — from the moment you trigger it to the instant it’s live (or failed) — and keeps a complete history so you can roll back to any previous successful version with a single API call. You can trigger deployments manually from a commit SHA or branch, or automate them so every push ships automatically.

Deployment lifecycle

A deployment moves through a series of statuses from trigger to completion. Understanding these states helps you monitor progress and diagnose failures.

Status	Description
`pending`	The deployment has been queued and is waiting for a build runner to pick it up.
`building`	Meridian is installing dependencies and building your app from source.
`deploying`	The build succeeded and Meridian is rolling out the new version to the environment.
`success`	The deployment completed and your new version is live.
`failed`	The build or deploy step encountered an error. Check `build_logs_url` or `deployment_logs_url` for details.
`cancelled`	The deployment was cancelled before it completed.
`rolled_back`	The environment was restored to a previous deployment. This status appears on the deployment that was replaced, not the rollback target.

pending → building → deploying → success
                               ↘ failed
                               ↘ cancelled
                  (rollback) → rolled_back

Triggering a deployment

From the dashboard

Navigate to the environment

In Hosting, select the environment you want to deploy to.

Click Deploy

Click Deploy in the environment header. A deployment form appears.

Specify the source

Enter the Git branch, commit_sha, or a version tag. You can also provide a commit_message for your records.

Confirm

Click Trigger deployment. The deployment appears at the top of the deployment history list with status pending.

Via the API

Send a POST request to create a new deployment:

POST /apps/:app_uuid/environments/:env_uuid/deploys

{
  "branch": "main",
  "commit_sha": "a1b2c3d4e5f6...",
  "commit_message": "feat: add subscription billing flow",
  "version": "v1.4.2"
}

All fields in CreateDeploymentRequest are optional. At minimum, provide either a branch or commit_sha so Meridian knows what to build. The response wraps the created deployment:

{
  "deployment": {
    "uuid": "dep_abc123",
    "env_uuid": "env_xyz789",
    "status": "pending",
    "branch": "main",
    "commit_sha": "a1b2c3d4e5f6...",
    "commit_message": "feat: add subscription billing flow",
    "version": "v1.4.2",
    "created_at": "2026-05-05T10:00:00Z"
  }
}

You can also deploy directly via the environment:

POST /environments/:env_uuid/deploys

Auto-deploy configuration

Meridian can automatically trigger a deployment every time you push to a specific branch. Configure this using two fields on your App object:

Field	Type	Description
`auto_deploy_target`	`string`	The environment name or UUID that receives auto-deployments
`auto_deploy_branch`	`string`	The branch that triggers auto-deploy when pushed

When both fields are set, any push to auto_deploy_branch triggers a new deployment to the auto_deploy_target environment automatically — no manual step required. You can also enable auto-deploy per-environment using the auto_deploy and branch fields on a CreateEnvironmentRequest or UpdateEnvironmentRequest. The environment-level setting gives you fine-grained control when you want different branches to auto-deploy to different environments (for example, main → production, develop → staging).

Connect your GitHub repository first before enabling auto-deploy. Meridian uses the git_provider, repo_owner, and repo_name fields on your app to resolve incoming push events to the correct deployment target.

GitHub integration

Meridian reads the following fields from your App to connect deployments to your repository:

Field	Type	Description
`git_provider`	`string`	The VCS provider (e.g., `"github"`)
`repo_owner`	`string`	GitHub user or organization that owns the repository
`repo_name`	`string`	Repository name
`github_installation_id`	`string`	The GitHub App installation ID that granted Meridian access

If repo_owner or repo_name are missing from your app, go to Settings → GitHub to connect your repository before triggering deployments.

Monitoring deployments

Build and deployment logs

Once a deployment is running, two log URLs become available on the Deployment object:

Field	Description
`build_logs_url`	Streaming URL for build-phase output (dependency install, compile, bundle)
`deployment_logs_url`	Streaming URL for deploy-phase output (container startup, health checks)

Fetch either URL to tail live logs during the deployment, or review them after the fact to diagnose failures.

GET /deploys/:deployment_uuid

{
  "uuid": "dep_abc123",
  "env_uuid": "env_xyz789",
  "status": "building",
  "build_logs_url": "https://logs.meridian.app/builds/dep_abc123",
  "deployment_logs_url": "https://logs.meridian.app/deploys/dep_abc123",
  "commit_sha": "a1b2c3d4e5f6...",
  "branch": "main"
}

Listing deployment history

To retrieve the full deployment history for an environment:

GET /environments/:env_uuid/deploys

This returns an array of Deployment objects sorted by creation time, newest first.

Rolling back a deployment

If a release introduces a regression, roll back to any previous successful deployment:

POST /deploys/:deployment_uuid/rollback

No request body is required. Meridian redeploys the specified version to the environment immediately. The rollback creates a new Deployment record with a fresh uuid, while the deployment that was live before the rollback transitions to status rolled_back.

Find the deployment to restore

In Hosting, open the environment and scroll through the deployment history. Locate the last known-good deployment.

Trigger the rollback

Click Roll back to this version next to the target deployment, or call POST /deploys/:deployment_uuid/rollback with the UUID of that deployment.

Verify

Watch the new deployment move through pending → deploying → success. Once it reaches success, your previous version is live again.

Rolling back does not restore database state. If your deployment included a database migration, rolling back the app code will not reverse the migration. Test rollback procedures in staging before relying on them in production.

Deployment fields reference

Field	Type	Description
`uuid`	`string`	Unique identifier for the deployment
`env_uuid`	`string`	The environment this deployment belongs to
`app_uuid`	`string` (optional)	The app this deployment belongs to
`status`	`DeploymentStatus`	Current status (see status table above)
`version`	`string` (optional)	Version tag (e.g., `"v1.4.2"`)
`commit_sha`	`string` (optional)	Full Git commit SHA
`commit_message`	`string` (optional)	Commit message for reference
`branch`	`string` (optional)	Git branch the deployment was built from
`build_logs_url`	`string` (optional)	URL to build-phase logs
`deployment_logs_url`	`string` (optional)	URL to deploy-phase logs
`deployed_at`	`string` (optional)	ISO 8601 timestamp when the deployment went live
`created_at`	`string` (optional)	ISO 8601 creation timestamp
`updated_at`	`string` (optional)	ISO 8601 last-updated timestamp

Next steps

Manage environments to create separate staging and production targets
Set up hosting and addons to attach a database to your environment

Get Started

Build

Deploy

Grow

App Store

Learn & Certify

Directory

Trigger deployments and roll back on Meridian

Deployment lifecycle

Triggering a deployment

From the dashboard

Via the API

Auto-deploy configuration

GitHub integration

Monitoring deployments

Build and deployment logs

Listing deployment history

Rolling back a deployment

Deployment fields reference

Next steps

Get Started

Build

Deploy

Grow

App Store

Learn & Certify

Directory

Documentation Index

​Deployment lifecycle

​Triggering a deployment

​From the dashboard

​Via the API

​Auto-deploy configuration

​GitHub integration

​Monitoring deployments

​Build and deployment logs

​Listing deployment history

​Rolling back a deployment

​Deployment fields reference

​Next steps

Deployment lifecycle

Triggering a deployment

From the dashboard

Via the API

Auto-deploy configuration

GitHub integration

Monitoring deployments

Build and deployment logs

Listing deployment history

Rolling back a deployment

Deployment fields reference

Next steps