Kernlift

Sync upstream updates

Merge new versions of the template into your project from the upstream remote, and accept them with the project's own checks.

Your project is a clone of a template repository that keeps moving. You take its updates by merging from an upstream remote. Merges stay small when you keep your changes in the directories that are yours to edit.

Before you begin

  • A clean working tree, committed or stashed.
  • Read access to the template repository on GitHub. See Get Kernlift.
  • Your project pushed to a private repository of your own, as origin. See Can I fork the repository?
  • CHANGELOG.md from the version you are moving to. Breaking changes are marked Breaking and carry migration instructions.

Keep your changes in your zone

ZonePaths
Yours to editsrc/config/site.ts, src/components/marketing/example-landing.tsx, src/i18n/locales, public
Template skeletonsrc/server, src/components/ui, scripts, drizzle/migrations, src/router.tsx, src/start.ts, src/server-entry.ts

The skeleton never imports from your zone, except src/config/site.ts. pnpm validate:template-boundary enforces that.

Merge an update

Add the upstream remote once

git remote add upstream git@github.com:kernlift/kernlift.git
git fetch upstream

For a business template, use that template's repository (kernlift/<template-key>) instead.

Merge the update on a branch

git fetch upstream
git checkout -b upgrade/upstream-update main
git merge upstream/main

Merge rather than rebase, so your project's commit history is not rewritten. When upstream has changed a lot since your last sync, take only what you need with git cherry-pick <commit> instead of merging everything at once.

Resolve conflicts

  • In your zone: keep yours, then check whether upstream added a key you also need. This usually happens in the message catalogues.
  • In the skeleton: take upstream, then reapply your change. If you do this repeatedly in the same file, move your change into a module the skeleton calls.
  • In drizzle/migrations: never edit an existing migration. Take upstream's chain as-is and add your own migration on top.
  • In package.json: take both sides' dependencies, then pnpm install.
  • In your deployment files (deploy.config.json and wrangler.jsonc, fly.toml, .railway/railway.ts or compose.yaml): keep yours. They record your platform and resource ids. If upstream changed the file for your platform, re-add its change by hand, then run pnpm cf-typegen.

Accept the update

pnpm install
pnpm cf-typegen
pnpm db:migrate
pnpm typecheck
pnpm build
pnpm validate:all

Push to your repository

git checkout main
git merge upgrade/upstream-update
git push origin main

Verify

  • Open /setup and confirm nothing required became Not ready.
  • pnpm validate:all shows no new failures. Compare against scripts/validate/known-failures.json on the upstream commit you merged.
  • To see which release you are on, run git describe --tags $(git merge-base HEAD upstream/main). Version tags match changelog entries one-to-one.

Troubleshooting

A new admin page says "Permission denied"

The update added permissions. Run pnpm db:bootstrap-super-admin again, with the same SUPER_ADMIN_EMAIL and SUPER_ADMIN_PASSWORD as in the quick start, so the Super Admin role receives them.

pnpm db:migrate fails after a merge

An existing migration was edited, or the two chains diverged. Restore upstream's migration files unchanged, add yours on top, and run pnpm validate:migrations.

The same skeleton file conflicts on every merge

You keep a change in a file upstream also edits. Move the change into your own zone, or into a plugin the skeleton calls, so the next merge does not touch it. See Plugins.

git fetch upstream says "Repository not found"

The GitHub account your git client uses is not the one you activated the purchase with, or the invitation was never accepted. Check Purchased templates (/app/licences); see My invitation expired.

Reference

Next steps