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.mdfrom the version you are moving to. Breaking changes are markedBreakingand carry migration instructions.
Keep your changes in your zone
| Zone | Paths |
|---|---|
| Yours to edit | src/config/site.ts, src/components/marketing/example-landing.tsx, src/i18n/locales, public |
| Template skeleton | src/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 upstreamFor 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/mainMerge 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, thenpnpm install. - In your deployment files (
deploy.config.jsonandwrangler.jsonc,fly.toml,.railway/railway.tsorcompose.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 runpnpm cf-typegen.
Accept the update
pnpm install
pnpm cf-typegen
pnpm db:migrate
pnpm typecheck
pnpm build
pnpm validate:allPush to your repository
git checkout main
git merge upgrade/upstream-update
git push origin mainVerify
- Open
/setupand confirm nothing required became Not ready. pnpm validate:allshows no new failures. Compare againstscripts/validate/known-failures.jsonon 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.