Upgrading Codapult

How Updates Work

Codapult uses git merge — the same approach used by Supastarter, Makerkit, and other premium boilerplates. You keep your customizations in your own repository and merge tagged releases from the upstream Codapult repo.

Your repo (main)     ──●──●──●──────●──●──── (your commits)
                             ↑              ↑
Codapult upstream   ──○──○──○──○──○──○──○── (our releases)
                        v1.0  v1.1  v1.2

Every release is a git tag (e.g. v1.2.0). You merge the tag into your repo, resolve any conflicts, and continue building.

The template and the developer tools are versioned independently:

• Template source is updated by merging a tagged release into your application repository.
• CLI commands are delivered through the published @codapult/cli package.
• MCP is pinned in .cursor/mcp.json and can be updated independently from the template.
• Guard is delivered through the published @codapult/guard package and follows its own release notes.

One-Time Setup

After purchasing Codapult, add the upstream remote using the GitHub access provided for the private repository:

git remote add codapult-upstream https://github.com/codapult/codapult.git

Verify it's configured correctly:

git remote -v
# origin   git@github.com:you/my-saas.git (your repo)
# codapult-upstream https://github.com/codapult/codapult.git (Codapult)

Update Process

1. Check Available Versions

git fetch codapult-upstream --tags
git tag -l 'v*' --sort=-v:refname | head -20

The CLI can perform the same upstream preparation and merge workflow:

npx @codapult/cli update --list
npx @codapult/cli update v1.2.0

It requires a clean working tree, fetches the codapult-upstream tags, and reports conflicts for manual resolution. Commit your product changes before starting an update.

2. Read the Changelog

Check CHANGELOG.md or the release notes for the target version. Pay attention to:

• Breaking changes — may require action on your side
• Migration steps — specific instructions for that version
• New features — optional modules you can enable/disable via ENABLE_* flag in src/config/env.ts and src/config/env-schema.ts.

3. Merge the Release

git merge codapult-upstream/v1.2.0 --no-commit

git diff --cached --stat  # review what changed

4. Resolve Conflicts

Review each conflict against both versions and preserve the intent of your product together with the upstream change.

Common conflict categories:

• Dependencies and lockfiles: merge the intended dependency set, then regenerate the lockfile with pnpm install.
• Database schema and migrations: preserve compatible changes from both sides, then review the resulting schema and migration order before applying it to a database.
• Configuration and environment: keep your deployment values and add new upstream settings where they are required.
• Translations and content: preserve your product copy while adding new keys required by upstream code.
• Generated or derived files: prefer regenerating them from the merged source instead of manually combining generated output.
• Application code: resolve behavior deliberately; do not accept one side solely because it is upstream or local.

5. Install and Verify

pnpm install
pnpm dev          # check the app works
pnpm lint         # check for type/lint errors
pnpm test         # run unit tests

6. Commit

git add .
git commit -m "chore: upgrade Codapult to v1.2.0"

7. Apply Schema Changes

If the release notes mention database changes:

pnpm db:generate  # generate new migration
pnpm db:push      # apply to dev database

CLI and MCP updates

Run the current published CLI with npx, or pin it as a dev dependency when your CI needs reproducible tooling. Update the MCP version recorded for your editor with:

npx @codapult/cli mcp update --dry-run
npx @codapult/cli mcp update 0.15.3
npx @codapult/cli mcp doctor

Use the actual released version available to your project; the version above is only an example. Review CLI and Guard release notes separately from template release notes.

General Recommendations

Codapult projects are regular Git repositories. You can change any part of the source code that your product requires.

To keep upgrades manageable:

• Keep product changes in small, reviewable commits.
• Pull updates regularly instead of accumulating a large gap between releases.
• Prefer additive changes and existing configuration, adapter, and plugin interfaces when they fit the requirement.
• Review every conflict against both versions; do not accept one side automatically.
• Run the app, lint, tests, and the relevant build checks after completing a merge.
• Read the release notes before applying a release with breaking changes or database migrations.

Version Numbering

Codapult follows Semantic Versioning:

Release cadence:

• Patches — as needed for bug fixes and security
• Minor — every 2–4 weeks with new features
• Major — rare, only for structural changes

Update regularly (every minor release). The longer you wait, the harder the merge.

Troubleshooting

Haven't updated in months

Option A — Incremental merge (recommended):

git merge codapult-upstream/v1.1.0 --no-commit && git commit -m "chore: upgrade to v1.1.0"
git merge codapult-upstream/v1.2.0 --no-commit && git commit -m "chore: upgrade to v1.2.0"

Option B — Cherry-pick specific fixes:

git log codapult-upstream/main --oneline
git cherry-pick <commit-hash>

pnpm-lock.yaml always conflicts

This is expected. Always resolve by accepting upstream and regenerating:

git checkout --theirs pnpm-lock.yaml
pnpm install
git add pnpm-lock.yaml

Edited core files and everything conflicts

For files in src/lib/auth/, src/lib/payments/, etc.:

1. Accept upstream: git checkout --theirs <file>
2. Re-apply your changes on top (or move them to plugins/config)

Going forward, keep your edits small and reviewable so conflicts are easier to resolve.

New database tables conflict with mine

In src/lib/db/schema.ts:

1. Keep both your tables and upstream's new tables
2. Make sure there are no duplicate table names
3. Run pnpm db:push to apply