Skip to content

Get started

Automatic updates

Your app ships with a GitHub Actions workflow, kit-update, that takes kit updates for you. Once a day it checks the kit, and when the kit has something new it does what pnpm kit:update does (Updating from the kit) on a branch of its own and opens a pull request. You read the pull request and merge it. You need this page once, to turn the workflow on, and again whenever a pull request asks something of you.

It serves an app that is the whole repository. An app in a folder of a monorepo keeps taking updates by hand.

How it works

  1. Every day at 05:17 UTC, GitHub runs kit-update in your app's repository. Until you turn it on, that run is skipped and does nothing.
  2. It reads .template-base on your default branch to see which kit commit your app is at, and asks the kit what changed since. When nothing did, it stops, in about a minute.
  3. When something did, it builds the update on a branch named kit-update, as one commit titled chore(template): update to main (or update to v1.4.0 on releases), and opens a pull request from it into your default branch.
  4. The pull request runs your CI like any other. Its description, and a status named kit-update, say whether it is safe to merge. GitHub notifies you of each new one.
  5. You merge it. Merging deploys it, like any other merge to your default branch. The next run proposes whatever the kit changed after it.

Turn it on

You need a token, so the workflow can act as you, and a variable that says which updates to take. Both go in your app repository's settings. The four steps below take about ten minutes, in this order.

Create a token

A personal access token is a password that GitHub issues for scripts, limited to what you allow. The workflow needs one because GitHub's built-in token cannot do this job: a pull request it opens waits for a click before any of your CI runs, and it can never push a kit change to a workflow file.

The simplest setup is one classic token. If you were invited to the kit repository, nuxter-app/kit, on your own, GitHub treats you as an outside collaborator there, and a classic token is the only kind it lets you use to read it.

  1. On GitHub, open your profile picture, then Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).
  2. In Note, write what it is for, such as kit-update for my-app.
  3. Pick an Expiration. From 30 days before that date, each run warns you, and so does a pull request it opens or rebuilds.
  4. Under Select scopes, tick repo and workflow.
  5. Press Generate token and copy it. GitHub shows it once.

A classic token reaches every repository your account can. To keep the token that pushes to your app narrower, use two tokens instead.

Add it to your app

  1. Open your app's repository on GitHub, then Settings → Secrets and variables → Actions.
  2. On the Secrets tab, press New repository secret.
  3. Name it KIT_UPDATE_TOKEN, paste the token as its value, and press Add secret.

Choose what to take

On the same page, open the Variables tab, press New repository variable, name it KIT_UPDATE_CHANNEL, and give it one of these values:

ValueWhat the daily run does
mainTakes every change on the kit's main, which is always deployable.
releaseTakes published releases only, such as v1.4.0.
offNothing: the daily run is skipped, as it is while the variable is not set.

You can switch at any time. Moving from main to release waits for a release newer than the kit commit your app is at. Releases says what a release number tells you.

Check that it works

  1. Open the repository's Actions tab and pick kit-update in the list on the left.
  2. Press Run workflow on the right, leave the fields as they are, and press the green Run workflow button.
  3. Open the run when it finishes. Its summary says what it did, such as The app already has the kit's main (…). or #12 proposes the kit's main (…), with a link to the pull request.

A red run says what to fix, as When a run fails lists.

On GitHub Free

On a personal account, or an organization on GitHub Free, set the secret and the variable in every app repository: a private repository there sees only its own. An organization on GitHub Team or Enterprise can set them once, under the organization's own Settings → Secrets and variables → Actions, for the repositories it picks.

A private repository on GitHub Free or Pro cannot have draft pull requests. Where the workflow would make the pull request a draft, because the update needs you first, it leaves it open for review instead, whether it opens the pull request or rebuilds one, and its Warnings section says so. The highlighted line and the red kit-update status are the warning too.

Two tokens instead of one

A fine-grained token can be limited to the app repositories you pick. Create it under Personal access tokens → Fine-grained tokens, with:

  • Resource owner: the account or organization that owns your app.
  • Repository access: only the app repositories.
  • Repository permissions: Contents, Pull requests and Workflows, each set to Read and write.

Organizations cap these tokens at 366 days by default, and one that targets an organization may wait for an owner to approve it. A fine-grained token reaches one owner's repositories only, so it cannot also read the kit. Add a second secret, KIT_READ_TOKEN, that can: a classic token with the repo scope if you were invited to the kit alone, or, if you are a member of the nuxter-app organization, a fine-grained token with nuxter-app as its resource owner and Contents read on the kit. The workflow reads the kit with KIT_READ_TOKEN when it is set, and with KIT_UPDATE_TOKEN otherwise. Runs warn of either token's expiry, from 30 days before.

Run it now

Actions → kit-update → Run workflow runs it without waiting for the next day. It needs KIT_UPDATE_TOKEN but not the variable. The form has three fields:

FieldWhat it does
Which kit to takeconfigured follows KIT_UPDATE_CHANNEL, and main when it is not set. main or release checks that channel once, even while the variable is off.
Rebuild the open pull requestA tick builds the open pull request again even when it still merges cleanly, unless its branch carries a commit of yours, and takes an update whose pull request you closed.
The kit commit this app last tookLeave it empty unless a run asks for it (When a run fails). It takes a kit commit or tag.

What each run does

  • The kit has nothing new for your channel: it stops in about a minute.
  • No kit update is open: it builds one on the kit-update branch and opens a pull request, as a draft when something needs you first.
  • A kit update is open: it leaves it alone, even when the kit has moved on. Merge it, and the next run proposes the rest. It builds the branch again only when the pull request no longer merges into your default branch, when your package.json, pnpm-lock.yaml or pnpm-workspace.yaml changed on the default branch, when your default branch was merged into it with nothing else changed, as GitHub's Update branch button does, or when you run it with Rebuild ticked.
  • You closed the pull request without merging: see Close the pull request.
  • You pushed a commit of your own to the branch, to settle a conflict for example: it leaves the branch alone while the pull request is open, and comments once on it when the kit has moved past it. Merge or close the pull request, and it carries on. A plain merge of your default branch does not count: the next run builds the branch again over it.
  • You took the update by hand with pnpm kit:update: if your default branch now has the kit's latest commit for your channel, the next run closes the pull request, or comments once that it is yours to close when the branch carries a commit of yours. If the kit has moved on since, the pull request counts as an open kit update, as above, and is rebuilt to propose the rest only for the reasons listed there.

Merge with Squash and merge or Create a merge commit, whichever your repository allows.

Read the pull request

The description opens with the two kit commits the update moves between, a link that compares them on the kit, and a highlighted line that says whether to merge. The kit-update status among the pull request's checks repeats it:

Highlighted lineStatusWhat to do
No conflicts with your files.GreenWait for CI, then merge.
Read before mergingYellowRead Before you merge and Conflicts first. The update changes production, or Claude resolved conflicts.
Do not merge yetRedA file needs you, the lockfile was not rebuilt, or the kit's changelog lists a step to take first. The line says which, and the pull request is a draft where drafts exist.

Under it, each section appears only when it has something to say:

  • Before you merge: the steps the kit's CHANGELOG.md added under Before you update, the new kit migrations that merging applies to your production database, every breaking kit commit, and a change to the kit's wrangler.jsonc, after which you check that every binding and resource name in yours still points at your app's own resources. A new changelog step makes the pull request a draft.
  • Conflicts: a table of every file git could not merge on its own, what each side did, and how it ended. A file both sides changed in different places merges without a conflict and is not listed. package.json is merged key by key when you and the kit changed different keys. pnpm-lock.yaml never needs merging by hand: when it conflicts, the kit's is taken, and whenever the kit changed package.json, pnpm-lock.yaml or pnpm-workspace.yaml, pnpm rebuilds the lockfile with your packages added back. A text file nobody resolved keeps its conflict markers, a binary file both sides changed keeps your version, a file you deleted stays deleted, and a file the kit deleted or moved keeps your version. Each says so and makes the pull request a draft.
  • Lockfile: why pnpm-lock.yaml could not be rebuilt.
  • Your files that replace kit files this update changed: the same list pnpm kit:update prints, with the command that shows each kit change (Your replacements the update changed). The update never touches these files. Carry over what your copy should have, a security fix above all.
  • Your dependencies the lockfile moved: your own packages that rebuilding the lockfile moved within their ranges.
  • Warnings: a token about to expire, a step the workflow could not finish, and the like.
  • Kit commits: the subject of every kit commit the update brings.

A comment from github-actions then mentions the owner of KIT_UPDATE_TOKEN, so the pull request reaches you as a notification even though your own token opened it.

Settle a conflict yourself

When Conflicts marks a file Not resolved, fix it on the branch:

git fetch origin
git switch -C kit-update origin/kit-update

A text file both sides changed keeps its conflict markers: edit it and remove them. A file kept deleted, a file the kit deleted or moved, and a binary file both sides changed already hold your side: leave them as they are, or bring in the kit's version by hand. Then commit and push any change:

git add -A
git commit -m "chore(template): settle the kit update's conflicts"
git push

Mark the pull request Ready for review if it is a draft, wait for CI, and merge. From your first commit on, the workflow leaves the branch alone until the pull request is merged or closed.

You can also close the pull request and take the update with pnpm kit:update on a branch of your own instead (Take an update).

Close the pull request

Closing a kit update without merging it skips that kit commit. The workflow does not open it again, and the next change to the kit opens a new pull request. That one starts from where your app is, so it brings the changes you skipped as well.

  • To take a skipped update after all, run the workflow with Rebuild ticked.
  • To stop for longer, set KIT_UPDATE_CHANNEL to off.
  • Commits you pushed to the branch stay reachable from the closed pull request.

Undoing one file's change on the branch and merging the rest declines that change for good: merging still moves .template-base to the new kit commit, so no later update brings it again.

Let Claude resolve conflicts

The workflow can hand the conflicted files to Claude Code before it opens the pull request. It is off until you add a variable and a secret:

NameKindValue
KIT_UPDATE_RESOLVERvariableclaude
ANTHROPIC_API_KEYsecretAn Anthropic API key, billed to that API account.
CLAUDE_CODE_OAUTH_TOKENsecretInstead of the key: a token from claude setup-token, billed to that person's Claude subscription.

The secrets alone never turn it on. Two optional variables tune it: KIT_UPDATE_RESOLVER_BUDGET caps each run at that many US dollars of Claude's own estimate, 5 when it is not set, and KIT_UPDATE_MODEL picks the model. Claude is billed only when an update has a conflict.

Claude Code gets the conflicted files only, with the kit's old and new version and your version of each beside them. It can read and edit files in the checkout and nothing else: no shell, no web, no GitHub token. It is never given these, which keep their conflicts for you or are settled by the workflow:

  • anything in layers/kit/ or .github/;
  • wrangler.jsonc, or a wrangler.json or wrangler.toml;
  • pnpm-lock.yaml, pnpm-workspace.yaml, .npmrc and a pnpmfile;
  • .template-base;
  • a binary file: when both sides changed one, your version is kept, and merging drops the kit's change to it for good.

The workflow checks its work before keeping any of it. If Claude edits a file it was not given, none of its work is kept. It cannot write to .git/, and if Git's config, attributes or hooks change anyway, the run stops and pushes nothing. A file it was unsure of, left markers in, or wanted to delete although both sides changed it goes back the way the update left it, for you to settle. When Claude resolved package.json, nothing it chose runs before you have read it, so the resolved files are left unformatted: run pnpm format on the branch if CI asks for it.

Each file's row in Conflicts says what Claude did and how sure it was. A pull request with conflicts Claude resolved is never green. It is Read before merging, or Do not merge yet when something else still needs you. Its merge is a proposal, and merging deploys it.

Your tests on the pull request

The pull request runs your CI once, like any other, and so does any workflow your organization requires on every pull request.

In an app, a plain pnpm test runs what your CI runs: your own suites and the kit suites that check your files and config. The kit's other suites test the config the kit ships, so they fail in an app that changed it for reasons that are not yours. pnpm test:e2e likewise runs only your own Playwright specs. The kit tells an app from itself by .template-base at the root, so a test workflow of your own that runs pnpm test runs the same suites your CI does. KIT_SUITES=all pnpm test --run still runs every kit suite. An app that has not taken its first update has no .template-base yet, and until then pnpm test runs everything (Testing).

When a run fails

A run fails when someone has to act, and GitHub emails whoever started it or last changed its schedule. The run's summary opens with the reason:

The run saysWhat to do
The KIT_UPDATE_TOKEN secret is not set.Add it.
GitHub refused KIT_UPDATE_TOKEN: it has expired or was revoked.Create a new token and replace the secret's value. KIT_READ_TOKEN can say the same.
KIT_UPDATE_TOKEN cannot see …Give the token access to this repository. A fine-grained token needs it in its list and, if it targets an organization, an owner's approval: until then it reads public repositories only. A classic token needs the repo scope and an account that can open the repository.
… cannot read nuxter-app/kitSet KIT_READ_TOKEN to a token that can read the kit (Two tokens instead of one): a fine-grained KIT_UPDATE_TOKEN never can, and a fine-grained nuxter-app token may still wait for an owner's approval. If your account lost access, see Losing access to the kit.
… changes a workflow file …Tick workflow on a classic token, or give a fine-grained one Workflows: Read and write.
… needs Contents: read and write or … needs Pull requests: read and writeGive the fine-grained token that permission.
KIT_UPDATE_CHANNEL is …; set it to main, release or off.Fix the variable's value.
layers/kit/ differs from the template's … in: and a list of filesMove each change into a file of yours (A changed layers/kit/ is refused).
No template commit matches this app’s first commit …Run the workflow by hand with the kit commit or tag your app started from in The kit commit this app last took.
A file and a folder clash at …Take this update with pnpm kit:update by hand and settle it there.
The kit-update branch has commits that are not the workflow's …Rename or delete your kit-update branch: the workflow needs that name.
.template-base names …, which nuxter-app/kit no longer has …Run the workflow by hand with the kit commit or tag in the kit's current history that matches the one your app last took in The kit commit this app last took. The hash in .template-base is no longer in the kit, so the run refuses it.

When the kit's history is rewritten and the run can find the kit commit that matches your layers/kit/, it uses that one and says so in the pull request instead of failing. A run that changed nothing for a reason that needs no one, such as an update whose pull request you closed or your default branch moving while it worked, ends green with a notice.

A GitHub outage is one of those reasons. When a read from GitHub's API meets an error on GitHub's side, or cannot reach GitHub, the run tries it again after 3 and then 10 seconds. If GitHub still fails while the run first reads your app, the kit and their pull requests, or fetches from them, the run stops before it has changed anything. Its notice says the problem is GitHub's, not a token's, and the next run tries again. An outage later in the run fails it like any other error.

Losing access to the kit

The workflow reads nuxter-app/kit with your token, as git fetch template does on your machine. If the account behind the token was removed from the kit repository, every run fails with KIT_UPDATE_TOKEN cannot read nuxter-app/kit (GitHub answered 404), or names KIT_READ_TOKEN when that one reads the kit. If the token belongs to someone who left your team and also lost your app's repository, the run usually stops one step earlier, at your own repository, with KIT_UPDATE_TOKEN cannot see ….

Your app keeps working and keeps every update it already took: only new updates stop. Replace the secret with a token from an account that can read the kit and your app, or set KIT_UPDATE_CHANNEL to off to stop the daily failures.

Good to know

  • A run that finds nothing new takes about a minute of Actions time. A run that opens a pull request takes a few, and the pull request then runs your CI once. The branch is built again only for the reasons in What each run does, so a busy kit does not mean a busy app.
  • In a monorepo folder the workflow does not run: GitHub reads workflows only from the repository root's .github/workflows/, and a copy moved there fails, because its step runs layers/kit/scripts/template/propose.mjs from the root. Take updates with pnpm kit:update (Apps in a subfolder).
  • kit-update is the workflow's branch name. Name a branch of your own anything but kit-update or a name under kit-update/, which makes the run's push fail. The kit-update-<date> that Take an update suggests is fine.
  • The workflow lives in your app's .github/workflows/kit-update.yml, which the kit owns, so kit updates bring its changes too.
  • Every action the workflow uses runs at a fixed commit, never a release tag such as actions/checkout@v7. Whoever controls an action's repository can move a tag to new code, which would then run in the job that holds your tokens. The kit's other workflows pin theirs the same way, so a newer release of an action reaches your app as a kit update that changes workflow files.