Upgrading to 2.x

Upgrade an existing Pages CMS 1.x deployment to 2.x.

Upgrade checklist

  1. Back up the deployment. Save the current database and environment configuration before changing anything.
  2. Optional: Migrate to PostgreSQL. Pages CMS 2.x expects PostgreSQL for normal deployments. If you still use SQLite or legacy libSQL/Turso, migrate collaborators first: Migrating collaborators.
  3. Update environment variables (see below)..
  4. Update the GitHub App (see below).
  5. Run migrations. Apply the 2.x database migrations before serving traffic: npm run db:migrate.
  6. Clear cache. Remove old cache data once after upgrading: npm run db:clear-cache.
  7. Redeploy the app. Restart the app with the new code and environment.
  8. Verify the upgrade. Confirm GitHub sign-in, repository installation, webhook delivery, build status display, and GitHub Actions triggering if you use it.

Add environment variables

  • BETTER_AUTH_SECRET: A random secret for the new auth library (Better Auth).
  • BASE_URL: This is now required.

More info: Environment variables

Clear cache after upgrading

Recommended once after upgrading to 2.x:

npm run db:clear-cache

This removes old cache data from previous versions and lets Pages CMS rebuild it with the 2.x cache logic.

Update GitHub App

More info: GitHub App

Add account permissions

Permission Value
Email addresses Read only

Add repository permissions

Permission Value
Actions Read and write
Checks Read only
Commit statuses Read only

Add webhook events

Event
Check run
Check suite
Status
Workflow run

Confirm URLs and install behavior

Setting Value
User authorization callback URL <BASE_URL>/api/auth/callback/github
Webhook URL <BASE_URL>/api/webhook/github
Setup URL <BASE_URL>/
Redirect on update Enabled
Request user authorization during installation Disabled