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
- Every day at 05:17 UTC, GitHub runs
kit-updatein your app's repository. Until you turn it on, that run is skipped and does nothing. - It reads
.template-baseon 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. - When something did, it builds the update on a branch named
kit-update, as one commit titledchore(template): update to main(orupdate to v1.4.0on releases), and opens a pull request from it into your default branch. - 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. - 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.
- On GitHub, open your profile picture, then Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).
- In Note, write what it is for, such as
kit-update for my-app. - Pick an Expiration. From 30 days before that date, each run warns you, and so does a pull request it opens or rebuilds.
- Under Select scopes, tick
repoandworkflow. - 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
- Open your app's repository on GitHub, then Settings → Secrets and variables → Actions.
- On the Secrets tab, press New repository secret.
- 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:
| Value | What the daily run does |
|---|---|
main | Takes every change on the kit's main, which is always deployable. |
release | Takes published releases only, such as v1.4.0. |
off | Nothing: 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
- Open the repository's Actions tab and pick kit-update in the list on the left.
- Press Run workflow on the right, leave the fields as they are, and press the green Run workflow button.
- 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:
| Field | What it does |
|---|---|
| Which kit to take | configured 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 request | A 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 took | Leave 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-updatebranch 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.yamlorpnpm-workspace.yamlchanged 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 line | Status | What to do |
|---|---|---|
| No conflicts with your files. | Green | Wait for CI, then merge. |
| Read before merging | Yellow | Read Before you merge and Conflicts first. The update changes production, or Claude resolved conflicts. |
| Do not merge yet | Red | A 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.mdadded 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'swrangler.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.jsonis merged key by key when you and the kit changed different keys.pnpm-lock.yamlnever needs merging by hand: when it conflicts, the kit's is taken, and whenever the kit changedpackage.json,pnpm-lock.yamlorpnpm-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.yamlcould not be rebuilt. - Your files that replace kit files this update changed: the same list
pnpm kit:updateprints, 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_CHANNELtooff. - 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:
| Name | Kind | Value |
|---|---|---|
KIT_UPDATE_RESOLVER | variable | claude |
ANTHROPIC_API_KEY | secret | An Anthropic API key, billed to that API account. |
CLAUDE_CODE_OAUTH_TOKEN | secret | Instead 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 awrangler.jsonorwrangler.toml;pnpm-lock.yaml,pnpm-workspace.yaml,.npmrcand 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 says | What 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/kit | Set 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 write | Give 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 files | Move 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 runslayers/kit/scripts/template/propose.mjsfrom the root. Take updates withpnpm kit:update(Apps in a subfolder). kit-updateis the workflow's branch name. Name a branch of your own anything butkit-updateor a name underkit-update/, which makes the run's push fail. Thekit-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.