Updating Tolk Starter

Your site is your own copy of the kit, and new versions of Tolk Starter reach it in two ways:

• A weekly pull request in your repository, opened by .github/workflows/tolk-update.yml. It brings the new version in, with the release notes of every version since yours.
• A card on the admin dashboard, for admins, saying a newer version is out.

The version your site is on is TOLK_VERSION in src/tolk/version.ts. Each release changes it, and merging the release brings the new value to your site. Never change it by hand: the update compares it with the kit's releases.

Set up the weekly pull request #

1. Make a token that can read the kit. On GitHub, under Settings → Developer settings → Personal access tokens → Fine-grained tokens, generate a token whose resource owner is the account or organisation that owns the kit's repository. Give it access to that repository only, with Contents: Read-only. GitHub asks for an expiry date; when the token expires, the workflow fails with a message saying to make a new one.
   • If GitHub does not offer the kit's repository there, a classic token with the repo scope works too. It can read every repository your account can, so keep it in this one secret.
2. Save it in your site's repository under Settings → Secrets and variables → Actions → New repository secret, as TOLK_TOKEN.
3. Let workflows open pull requests: under Settings → Actions → General, tick "Allow GitHub Actions to create and approve pull requests". The Payload upgrade needs it too.
4. Allow merge commits under Settings → General → Pull Requests. An update must be merged with one (see Merge with a merge commit).
5. Check now: run Tolk update from the Actions tab.

Without TOLK_TOKEN, the workflow does nothing but say in its run summary how to add one; it never fails for that. To stop the weekly check altogether, disable the workflow in the Actions tab.

A site made from a version that did not have the workflow yet takes in one version by hand first (see By hand). From then on the pull requests come by themselves.

Where the kit lives #

The workflow reads the kit's releases from the repository named by TOLK_UPSTREAM in src/tolk/version.ts, today LasseNorby1/tolk. The kit moves to the tolkhq organisation later. GitHub forwards the old name until then, and the release after the move changes the default. If your site is not on that release yet, set the repository variable TOLK_UPSTREAM (Settings → Secrets and variables → Actions → Variables) to the new name, such as tolkhq/tolk.

The pull request #

Every Tuesday morning the workflow compares TOLK_VERSION with the kit's newest release; drafts and pre-releases never count. When the release is newer, it merges it on a branch tolk/update-<version> and opens a pull request, chore(tolk): update Tolk Starter to <version>:

• When the release merges cleanly, the branch holds the merge and a second commit with the lockfile, the types and the import map made again, and a Postgres migration if the merged config changes the tables. CI is started on the branch.
• When it conflicts with changes made in your repository, nothing is resolved for you. The branch is the release itself, so GitHub lists the conflicts on the pull request and offers its editor for the simple ones. Conflicts only in generated files (src/payload-types.ts, the import map, pnpm-lock.yaml) do not count: the workflow makes those again, as you would.
• A new major version (1.0 after 0.x, 2.0 after 1.x) says "(major version)" in the title, and the description points at its breaking changes. The description does that for any update whose release notes list breaking changes.

The description holds the release notes of every version between yours and the new one, the files that conflict, if any, and a checklist: CI, the release notes, the new migrations, and how to merge.

• One pull request per version. While the branch tolk/update-<version> exists, the workflow opens no other for that version. Delete the branch to have it opened again.
• A newer release gets a pull request of its own, which includes the earlier versions. Close the older one.

Merge with a merge commit #

Merge an update with Create a merge commit, never squash or rebase. A merge commit keeps the kit's commits in your history, so git knows which version your site has, and the next update compares against it and brings only what is new.

A squash-merged update #

After an update was squash-merged, git no longer knows your site has that version. When the next release merges cleanly, the workflow notices and records it first: a merge of the release your site is on that keeps your files as they are. The pull request says so.

When the release conflicts, the pull request may also list changes your site already has. Resolve it on your machine with the same record first. With the kit as the remote kit, and 0.5.0 and 0.6.0 standing for your version and the new one:

git fetch kit --tags
git switch -c tolk/resolve-0.6.0 origin/main
git merge --strategy=ours v0.5.0    # git now knows the site has 0.5.0
git merge v0.6.0
# Resolve the conflicts, make the generated files again (below), then:
git push origin HEAD:tolk/update-0.6.0

The push moves the update branch forward, as it already holds the release, and the pull request becomes mergeable.

Resolving conflicts #

Simple conflicts can be resolved on GitHub (Resolve conflicts on the pull request), all of them on your machine:

git fetch origin
git switch tolk/update-0.6.0
git merge origin/main
# Fix each conflict and git add the file, then make the generated files again:
pnpm install
pnpm generate:types
pnpm generate:importmap
git add -A
git commit
git push

In each conflict, keep both sides' intent: the release's change and yours. Some files need a word of their own:

• Generated files (src/payload-types.ts, src/app/(payload)/admin/importMap.js, pnpm-lock.yaml): take either side, then make them again with the commands above.
• package.json: keep your dependencies and the release's. If you renamed or re-versioned your package, keep your name and version.
• src/migrations/index.ts: keep both sides' entries, in the order of their names.

Then make a migration if the merged config changes the tables: pnpm payload migrate:create <name> with a postgres:// DATABASE_URL (see The database). Push the resolution and CI runs everything, on both databases. Run pnpm lint, pnpm typecheck, pnpm test:unit and pnpm test:int first if you like.

Releases that change workflows #

GitHub never lets a workflow's own token push changes to files in .github/workflows. When a release changes a workflow, the update cannot push its branch, so it opens an issue instead, with the commands to take the release in by hand.

To have such releases arrive as pull requests too, add a second secret, TOLK_PUSH_TOKEN: a fine-grained token for your site's own repository with Contents: Read and write and Workflows: Read and write. The workflow then pushes with it. A weekly run skips a version that has an issue already; run Tolk update from the Actions tab to try again after adding the secret.

By hand #

With the kit's repository as the remote kit (see Install), for the new version 0.6.0:

git fetch kit --tags
git switch -c tolk/update-0.6.0 origin/main
git merge v0.6.0
# Resolve any conflicts, then make the generated files again:
pnpm install
pnpm generate:types
pnpm generate:importmap
git add -A
git commit
git push -u origin tolk/update-0.6.0

Open a pull request, let CI run, and merge it with a merge commit.

The dashboard card #

When a newer version is out, admins see a card at the top of the dashboard, under the site's name: the version your site runs and the new one, the release's main points, and links to its release notes and to this page. Editors and translators never see it. The links lead wherever the list of releases says; while that is the kit's repository on GitHub, only people with access to it can open them.

• What it sends: once a day the server, never a visitor's or an admin's browser, reads the public list of releases at https://tolkhq.com/releases.json. It is one plain GET with the user agent tolk-update-check, and nothing else: no cookies, no address of your site, no version, no account. The server compares the list with TOLK_VERSION itself.
• When the list cannot be read (missing, slow beyond three seconds, or not a list of releases), there is no card and no error, and the next try is a day later.
• Turn it off with TOLK_UPDATES=off. The tests, and the tools that take the docs' screenshots and record the walkthrough, keep it off.
• Another list: TOLK_UPDATES_URL names it. The tolkhq.com domain is coming; until it answers, the card simply does not show.

The card says a version is out; the weekly pull request is how it reaches the site.

For the kit's maintainer #

The releases list is made from CHANGELOG.md, to publish with the landing page at the address above:

pnpm exec tsx scripts/tolk/releases-feed.ts > releases.json

It lists every release, newest first, each with its date, a link to its notes and its main points (breaking changes first, then features, then fixes):

{
  "guide": "https://tolkhq.com/docs/updating-tolk",
  "versions": [
    {
      "version": "0.5.0",
      "date": "2026-10-11",
      "url": "https://github.com/LasseNorby1/tolk/releases/tag/v0.5.0",
      "highlights": ["Render the demo's product pictures and video from code"],
      "breaking": false
    }
  ]
}

• Links go to each GitHub release and to this page on GitHub, which a site's admins may not be able to open. --notes-url 'https://tolkhq.com/changelog#{version}' and --guide-url 'https://tolkhq.com/docs/updating-tolk' name public pages instead; without --guide-url the list has no guide, and the card links the kit's docs. --highlights 3 keeps fewer main points (five by default), and --out writes a file.
• Releases are the kit's own. .github/workflows/release.yml runs only in the kit's repository, so a site's release-please never overwrites TOLK_VERSION, and the update workflow runs everywhere else. Both name the repository in their if:, and a unit test keeps them equal to TOLK_UPSTREAM. When the kit moves, change all three.
• A site that versions itself with release-please changes the if: in release.yml to its own repository and removes src/tolk/version.ts from extra-files in release-please-config.json. That line is the kit's version, not the site's.