# Deployments, rollback & redeploy
URL: https://synquic.tech/docs/guides/rollback-redeploy.md

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.

import { Step, Steps } from 'fumadocs-ui/components/steps';

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.

<Callout title="What you need first">
- A project that has been deployed at least once.
- Nothing else: rollback and redeploy work on deployments you already have.
</Callout>

## 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](#pin-a-version-so-its-always-there)). |

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](/docs/guides/logs-monitoring)).

From the terminal:

```bash
# 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> --follow
```

## The 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

<Steps>

<Step>

### 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.

</Step>

<Step>

### 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.

</Step>

<Step>

### 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.

</Step>

</Steps>

<Callout title="Why rollback is quick, and safe for your data" type="info">
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.
</Callout>

<Callout title="The rollback option is greyed out" type="warn">
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.
</Callout>

<Callout title="Multi-service and static projects" type="info">
- **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.
</Callout>

## 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](/docs/guides/deploy-docker-image#track-new-versions)).

<Callout title="Rebuild one specific old commit" type="info">
**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).
</Callout>

## 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.

<Callout title="Good to know" type="info">
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.
</Callout>

## CLI

List the deployments to get their IDs:

```bash
# 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:

```bash
# 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> --off
```

<Callout title="Tip" type="info">
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.
</Callout>

## Troubleshooting

<Callout title="“This deployment is already active”" type="error">
You are trying to roll back to the version that is already live. Pick a different row; the one serving is
marked **Active**.
</Callout>

<Callout title="“Only successful deployments can be rolled back to”" type="warn">
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.
</Callout>

<Callout title="The site still looks wrong after rolling back" type="warn">
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](/docs/guides/backups-restore) or fix it directly.
</Callout>

## Related guides

<Cards>
  <Card title="Auto-deploy on push" href="/docs/guides/auto-deploy" description="Ship every commit automatically, and roll back just as easily when one misbehaves." />
  <Card title="Deploy hooks" href="/docs/guides/deploy-hooks" description="Trigger a redeploy from CI or any tool with a URL." />
  <Card title="Multi-service apps" href="/docs/guides/compose-multi-service" description="How redeploy and rollback behave for several services at once." />
</Cards>