Skip to main content
Shipyard keeps a record of every successful deployment, including the commit hash that produced it. If a bad push reaches production, you can roll back by pointing Shipyard at a previous deployment — it re-runs the full build from that commit and replaces the current deployment files.

​
How rollback works

  • Each time a build succeeds and the project has no secrets, Shipyard writes a deployment record to the database linked to that build.
  • Rollback does not swap files directly. It re-runs the complete build engine using the previous deployment’s commit hash: the repo is cloned at that exact commit, the Docker image is built, and the build command runs again.
  • On success, the previous deployment’s output overwrites the current deployments/<project-name>/ directory on disk.
  • The project’s productionUrl (and therefore the subdomain) does not change — users continue to reach the same URL.
  • Because rollback re-uses the existing deployment record rather than creating a new one, the deployment table is not polluted with duplicate entries.

​
Step-by-step rollback

1

Get your projects and deployment IDs

Fetch your projects to find the deployment IDs you need. Each project in the response includes its builds, and each build includes its linked deployment.
curl https://your-server/api/project/projects \
  -H "Authorization: Bearer <your-jwt>"
Identify the id of the current (live) deployment — this is latest — and the id of the deployment you want to revert to — this is prev.
2

Call the rollback endpoint

Pass both IDs as query parameters to PUT /api/deploy/rollback:
curl -X PUT "https://your-server/api/deploy/rollback?latest=<latestDeploymentId>&prev=<prevDeploymentId>" \
  -H "Authorization: Bearer <your-jwt>"
Shipyard marks the current deployment as rolled_back, creates a new build record seeded with the previous deployment’s commit metadata, and immediately starts building.
3

Monitor the build via Socket.io

Rollback triggers the same build pipeline as a regular push. Connect to the Socket.io server with your JWT and listen for the standard build events in your project’s room. See the local testing guide for a Socket.io connection example.The buildStatusUpdate event tracks progress through running → passed or failed. When the build completes successfully, deploymentUpdate fires with the live URL confirming the rollback is complete.
Rollback triggers a full re-build from the previous commit — it is not a simple file swap. The Docker image is rebuilt from scratch, so the rollback takes as long as the original build did. Any transient infrastructure issues from the original build can affect the rollback as well.
When rolling back, a new deployment record is not created. The build engine’s isRollback flag tells the deployment engine to skip the INSERT into the deployments table, reusing the existing record. This means the deployment history reflects the original deployment rather than adding a new entry for the rollback.

​
When rollback isn’t available

Projects that have secrets stored cannot be auto-deployed by Shipyard. The same restriction applies to rollbacks: if the project has any secrets configured, the build engine will run but the output will not be deployed after the build passes. Remove secrets from the project or delete them individually via DELETE /api/project/secret/:secretId if you need deployment to proceed.

Build docs developers (and LLMs) love

Get started for freeTalk to us