Deployments, rollback & redeploy
Find every deployment and its logs, undo a bad deploy in seconds, run one again, and keep a known-good version safe, from the panel or the terminal.
Every project keeps a history of its deployments, like the version history of a document. If a new deployment turns out broken, you can switch the project back to a version that worked. When you just want to run the same thing again (after a fix, or to pick up the latest commit), you redeploy. This guide covers the list and its logs, rollback, redeploy, and pinning a good version so it is always there to fall back to.
What you need first
- A project that has been deployed at least once.
- Nothing else: rollback and redeploy work on deployments you already have.
Find your deployments
There are two lists:
- One project: open the project, then the Deployments tab. At the top is the Deploy Latest Changes card with Redeploy Project; below it, the project's history.
- Every project: Deployments in the sidebar. The All Projects menu narrows it to one project, and the sidebar shows totals (Successful, Failed, In Progress) and the most recent ones.
Both lists are newest first, with Search deployments... and status filters (All, Success, Failed, Building, Canceled) that apply to the whole history, not just the page you are on. Use the page controls at the bottom for older deployments.
Each row shows the version (like v3), a status, the commit, and labels:
| Label | Meaning |
|---|---|
| Active | The version currently serving the project. |
| Snapshotted | Synq still has this version's finished build, so rolling back to it skips the build. |
| Pinned | Kept forever; never cleaned up (see Pin a version). |
A row without a commit message (an upload, an image, a manual run) reads Manual deploy. Statuses include Deployed, Failed, Canceled, Building, Deploying, Verifying, Pending, Partial (some services of a multi-service deploy failed), Action required (the deploy is waiting for your answer), Rejected and No changes.
Read a deployment's logs
- Click a row to open its build screen (
/build/<id>): the step tracker (clone, build, deploy and so on), the Deployment Logs panel with the full build output, and the Details card (instance, build, build time, framework, domain). The status and branch are in the page header. For a deployment that is still running, the logs stream live. After a successful deploy of a server app, the same panel switches to the running app's container logs. - Click the commit hash on a row to open the commit on GitHub, or the Commit Details window (changed files, status, environment) for other sources.
- For the running app's logs over time, use the project's Logs tab (see Logs & monitoring).
From the terminal:
# The latest deployment of the linked project, or a specific one
synq logs
synq logs <deployment-id> --tail 200
# Follow a deployment that is still running
synq logs <deployment-id> --followThe deployment menu
The ⋮ menu on each row has:
| Item | What it does |
|---|---|
| Open Deployment | Opens the deployed site (when it has a domain). |
| View Repository | Opens the repository (GitHub projects). |
| Copy Domain URL / Copy Build ID | Copies the site URL or the deployment ID. |
| Cancel Deployment | Stops a deployment that is still building or deploying. |
| Rollback to this version | Restores the project to this version. See below. |
| Pin / Unpin | Keeps this version's build forever, or lets it be cleaned up again. |
| Delete Deployment | Removes the row from the history. |
Roll back to a version that worked
Open the version you want to return to
Find the last row that was healthy. If it shows Snapshotted, Synq still has its build and the rollback is near-instant. If not, you can still roll back: Synq rebuilds that version's commit. It is the same menu item either way. Click the row's ⋮ menu.
Choose Rollback to this version
Synq tells you which route it will take:
- Instant restore: reuses this version's retained image, no rebuild.
- Rebuild: this version's image is no longer on the host, so its commit is built again.
- Registry restore: pulls the exact image reference recorded for this release; no source rebuild (image projects and registry images).
- Mostly instant: for a multi-service project where some services lost their image; only those are rebuilt.
Review and confirm
Roll back to this version? reminds you that it "restores the application code only. Database and volume data are unchanged." It also lists what happens to Environment variables: how many change, whether this release's values are replayed over the current ones or used exactly as captured, and which keys come back, are kept, or are dropped (values are never shown). Services added since that release are listed as untouched.
Press Roll back. Synq brings that version back as a new entry in the history. Nothing is erased: the version you rolled away from stays in the list, so you can roll forward the same way.
Why rollback is quick, and safe for your data
When the version's build is still on the server, rolling back rebuilds nothing; Synq ships the saved build again:
- It's fast. Your site is back in seconds, not the minutes a build takes.
- It restores that version's settings too: the environment variables, port, volumes and resource limits it ran with.
- Only your code changes. Databases and saved files (volumes) stay exactly as they are.
If the build has been cleaned up, Synq rebuilds that version's commit instead. Slower, but it lands in the same place.
The rollback option is greyed out
Only two things disable it: the version is already Active, or it never finished healthy ("Only ready deployments can be rolled back to"). A version with neither a saved build nor a commit to rebuild from (a one-off manual deploy, say) says so in the menu. To keep a version instantly restorable, pin it.
Multi-service and static projects
- Several services? Only the services whose build is missing are rebuilt. A service the deploy never touched keeps running on the image it already has, so rolling back your app code does not restart your database.
- Static site? The saved files for that version are restored; no image is involved.
Redeploy (run it again)
Redeploying builds and ships the project again. Use it after you push a fix, change settings, or want the live site to pick up the newest commit.
On the Deployments tab, press Redeploy Project. Synq pulls the latest commit on the deploy branch (or reuses the uploaded files or configured image), applies the project's current settings and environment variables, and creates a new version. You land on the build screen.
The caret (⌄) next to the button has two more choices:
- Refresh env: redeploy so the app picks up environment variable changes you just made.
- Rebuild all: rebuild every service instead of only the ones whose files changed. Shown only for multi-service projects.
The project toolbar also has Deploy ("Pull the latest commit and redeploy with the saved configuration") and Rebuild ("Rebuild every service, not only the ones that changed").
For an image project, when a newer version is found, the tab shows New version available with Deploy new version (see Deploy a Docker image).
Rebuild one specific old commit
Rollback to this version reuses a saved build when it can and rebuilds the commit when it can't. To
force a from-source rebuild of a specific commit even when its build is saved, use the terminal:
synq deployment redeploy <id> --use-existing-commit (below).
How many versions stay instantly restorable
Open the project's Advanced tab, Rollback history, to set the maximum number of past deployments whose builds are kept. The default is 5, inherited from the instance's default unless you set a project override. Disk measurements are informational; they do not change this limit. The same setting is in the deploy screen.
The active deployment and pinned deployments are kept in addition to this window. A multi-service deployment counts once, even if it needs several images. Set the limit to 0 to keep only active and pinned releases.
Cleanup runs after deployments finish, when you save a limit, and when you unpin a deployment. The scheduled Deployment artifact cleanup job retries failed cleanup and reconciles existing history; you can also run it by hand from Jobs. Cleanup waits for any running deployment worker to finish.
Older rows stay in the history but lose their Snapshotted label once their builds are removed. An image or file tree still needed by an active, pinned or retained deployment stays on the host until its last reference expires. Operator-managed and third-party registry images are not removed.
Rollback checks what is actually available. Expired source builds can be rebuilt from their recorded commit; image releases can be pulled again from their recorded reference. Bare hosts without a restartable supervisor unit rebuild from source. A release with neither a usable build nor a reproducible source cannot be restored.
Pin a version so it's always there
For a known-good version you always want to snap back to instantly, pin it: pinned versions are exempt from cleanup and don't count against the window.
In a row's ⋮ menu, choose Pin. To lift it, choose Unpin. A version whose build was already cleaned up cannot be pinned; its Pin item is disabled.
Good to know
You can pin up to 10 deployments per project. Pin your last reliable release before trying something risky; rollback is then always one click away, with no rebuild.
CLI
List the deployments to get their IDs:
# This project's deployments, newest first. The "active" column marks the live one.
# Run it in your linked project folder, or target another with --project <project-id>.
synq deployment list
# One deployment in detail (status, commit, url, whether it's pinned)
synq deployment get <deployment-id>Then act on one by its ID:
# Roll back to a previous deployment (the ID of the one you want to return TO)
synq deployment rollback <deployment-id>
# Redeploy from an existing deployment: picks up the latest commit on its branch
synq deployment redeploy <deployment-id>
# ...or rebuild that deployment's exact commit instead of the latest
synq deployment redeploy <deployment-id> --use-existing-commit
# Cancel one that is still running
synq deployment cancel <deployment-id>
# Pin a deployment so it's never cleaned up (add --off to unpin)
synq deployment pin <deployment-id>
synq deployment pin <deployment-id> --offTip
To ship the latest commit of the whole project (the terminal version of Redeploy Project), run
synq deploy in the project folder, or synq deploy --project <project-id>. Use synq deployment redeploy
to re-run one specific deployment from the history.
Troubleshooting
“This deployment is already active”
You are trying to roll back to the version that is already live. Pick a different row; the one serving is marked Active.
“Only successful deployments can be rolled back to”
You can only return to a version that finished healthy. A failed or cancelled deployment is not a valid restore target; choose the last row with a deployed status.
The site still looks wrong after rolling back
Rollback changes code only; it never touches your database or saved files. If the problem was a data change or a migration, rolling back the code will not undo it. Restore your data from a backup or fix it directly.
Related guides
Deploy hooks
Give a project its own URL that redeploys it (or runs a job) when called, from CI, a registry, a cron service or a script. Covers token, HMAC and open authentication, service selection, responses and the delivery log.
Deploy with synq.json
Add a declarative synq.json to your repo so Synq builds and deploys it the same way every time — in the wizard and headlessly on push.