> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jun.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade

> Each Jun release arrives in your copy as a pull request; merging deploys it, with database migrations applied first.

Jun ships as versioned [releases](https://github.com/samarsheikh001/jun/releases). Your copy of the repo gets each one as a pull request; merging it deploys. Deploying applies database migrations **before** the new Worker goes live, so new code never runs against an old schema.

## What carries over

Everything you have keeps working across an upgrade:

* the workspace, teammates and their passkeys,
* conversations and messages, contacts, and visitors' tokens (so a visitor's browser still finds its chats),
* the widget key, so the snippet on your site doesn't change,
* knowledge sources, their indexed chunks and vectors,
* the agent config (`instructions.md`, tasks, actions, widgets, tests) and its version history,
* settings and keys kept in Durable Object storage: issue tracker keys, action keys, the Web Push key.

Sessions survive too, so teammates stay signed in.

## Update with a pull request

Every copy of Jun has a GitHub Actions workflow, **Update Jun** (`.github/workflows/update-jun.yml`). Once a day it checks for a new release. When there is one, it opens a pull request in your repo, or updates the one already open, so you never get more than one.

<Steps>
  <Step title="Review the pull request">
    It's called **Update Jun to vX.Y.Z** and links the release notes. The new version is merged into your files:

    * files you never changed take the new version,
    * your own changes stay,
    * your Worker, database, bucket and queue names in `wrangler.jsonc` are kept,
    * a file both you and Jun changed in the same place is listed under **Resolve before merging**, with `<<<<<<<` markers to edit on the `jun-update` branch.
  </Step>

  <Step title="Merge it">
    A Deploy button install redeploys on its own: Workers Builds runs `npm run deploy` for the push. Follow it in the Cloudflare dashboard under the Worker's **Deployments**. A command-line install: pull `main`, then run `npm install && npm run deploy`.
  </Step>
</Steps>

Owners and admins see **Update to vX.Y.Z** in the desk's sidebar when a release is out, and the version under **Settings → General**. To check right away, open your repo's **Actions → Update Jun → Run workflow**.

<Note>
  If the workflow can't open pull requests in your repo, it opens an issue with a link to the pull request instead. To let it open them itself, turn on **Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests** in your repo.
</Note>

<Note>
  Cloudflare may show a failed **Workers Builds** check on the pull request. That's its branch preview (`wrangler preview`), which needs separate preview resources Jun doesn't set up, not the update: the build runs before it, and merging runs the normal deploy. To stop branch builds, open your Worker in the Cloudflare dashboard → **Settings → Build → Branch control** and turn off **Builds for non-production branches**.
</Note>

### A copy made before the workflow

Copies made before Update Jun existed don't have it yet. Add it once:

<Steps>
  <Step title="Add the workflow">
    In your repo on GitHub, choose **Add file → Create new file**, name it `.github/workflows/update-jun.yml`, and paste [the workflow from the Jun repo](https://github.com/samarsheikh001/jun/blob/main/.github/workflows/update-jun.yml). Commit it to `main`.
  </Step>

  <Step title="Run it">
    **Actions → Update Jun → Run workflow.** The first pull request brings every file up to the release, keeping your resource names.
  </Step>
</Steps>

<Warning>
  Don't `git pull` the Jun repo into a copy made by the Deploy button. The button's copy starts from its own first commit, with no history in common with Jun, so Git refuses the merge ("refusing to merge unrelated histories"). The workflow merges file by file instead.
</Warning>

The workflow never changes files under `.github/workflows/`: GitHub doesn't let a workflow edit workflows. When a release changes `update-jun.yml`, the pull request says so; copy the new file by hand.

## Upgrade a clone by hand

A clone of the Jun repo (not a Deploy button copy) shares its history, so you can also pull a release yourself:

```sh theme={null}
git pull https://github.com/samarsheikh001/jun v0.2.0
npm install && npm run deploy
```

`npm run deploy` runs `scripts/deploy.ts`: it builds with Vite, runs `wrangler d1 migrations apply DB --remote`, then `wrangler deploy`. If a migration fails, it stops before deploying, and the old Worker keeps running on the old schema.

To apply migrations on their own, run:

```sh theme={null}
npm run db:migrate
```

## Migrations

Migrations are SQL files in `migrations/`, numbered in order (`0001_init.sql`, `0002_conversations.sql`, …). Wrangler records which ones have run in the database, so each runs once. Some migrations move data into a new shape; for example, the AI's old free-text guidance became the agent's instructions file (`instructions.md`) and visitors' tokens moved to their own table.

Durable Object classes have their own migrations in `wrangler.jsonc` (`"tag": "v1"`, `"v2"`, …). Wrangler applies them as part of the deploy.

## Check an upgrade yourself

`scripts/upgrade-check.ts` is the test for upgrades. It seeds a desk running an older version, you upgrade that same database to the new code, and it checks that everything survived. It passes from the first AI release (M2) onwards.

It seeds:

* an owner account and workspace,
* AI settings with custom guidance and a monthly cap,
* a knowledge snippet,
* a visitor's conversation with a teammate's reply.

After the upgrade it verifies that the owner gets back in (through `/recover`) to the same workspace, the old conversation and widget key are intact, the visitor's old token still works, knowledge is still searchable, the old guidance became `instructions.md`, the AI answers a new question from the old knowledge, and Get started and the live visitor socket work on the old data.

<Steps>
  <Step title="Run the old version and seed it">
    Check out the old version, start it locally on its own port, then seed it:

    ```sh theme={null}
    BASE_URL=http://localhost:5175 node scripts/upgrade-check.ts seed state.json
    ```
  </Step>

  <Step title="Upgrade the same database">
    Check out the new version and point it at the same local state: apply the migrations, then start it.
  </Step>

  <Step title="Verify">
    ```sh theme={null}
    BASE_URL=http://localhost:5174 node scripts/upgrade-check.ts verify state.json
    ```
  </Step>
</Steps>

The script reads `SETUP_TOKEN` from the environment or from `.dev.vars`, and the AI step answers through the provider the seed turned on (Workers AI). See [Local development](/deploy/local-development) for running the desk locally with its own state directory.

<CardGroup cols={2}>
  <Card title="Deploy to Cloudflare" icon="cloud" href="/deploy/cloudflare">
    The Deploy button and the command-line route.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/reference/troubleshooting">
    When a deploy or upgrade goes wrong.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.