Skip to main content
Refract ships as a private GitHub repository you own as a collaborator. When new versions ship — new adapters, bug fixes, architectural improvements — you pull them in the same way you’d pull from any upstream remote. No forced upgrades, no breaking changes without warning.

​
How it works

When you purchased Refract, you were added as a collaborator with pull access to the private repository. Your project has two remotes:
  • origin — your own repository where your product lives
  • upstream — the Refract repository where updates come from
Updates flow one way: from upstream into your origin. You decide when to pull and how to handle conflicts.

​
Initial setup

If you haven’t added the upstream remote yet, do it once: 
git remote add upstream https://github.com/refract/bp-template.git
git fetch upstream
Verify both remotes are set up: 
git remote -v
You should see both origin and upstream listed.

​
Pulling an update

When a new version ships, you’ll be notified in #announcements on Discord. Here’s how to pull it into your project:
  1. Fetch the latest from upstream: 
    git fetch upstream
  2. Check what’s changed: 
    git log upstream/main --oneline
  3. Merge into your branch: 
    git merge upstream/main
  4. Resolve any conflicts (see Handling conflicts below).
  5. Verify everything still works: 
    make fresh-start
make test-all
Always run make test-all after merging an update. If tests pass, the merge is safe. If they don’t, the output will tell you exactly what broke.

​
Handling conflicts

Most updates won’t conflict with your code — Refract’s changes tend to happen in infrastructure and tooling files, while your product code lives in different areas. The files most likely to conflict:
FileWhy
apps/backend/src/configuration/development.tsNew config fields added
apps/backend/src/core/billing/Billing improvements
apps/backend/src/core/auth/Auth improvements
compose.ymlNew services or updated ports
MakefileNew make targets
When in conflict, the rule is simple: keep your product logic, take Refract’s infrastructure improvements. If you’re unsure, paste the conflicting section in #help on Discord and I’ll tell you which side to take. 
git status                  # see what's conflicting
git add <resolved-file>     # mark each file as resolved after editing
git commit                  # complete the merge
The smaller and more focused your changes to Refract’s core files, the fewer conflicts you’ll have. If you find yourself heavily modifying compose.yml or core configuration files, consider whether those changes belong in your product layer instead.

​
What updates include

Updates are announced in #announcements on Discord with a summary of what changed. They generally fall into these categories: New adapters — new providers for existing tools (e.g. a Resend mailer adapter, a new deployment strategy). These are additive — no conflicts expected. Bug fixes — fixes to existing behaviour. Usually safe to take wholesale. Architectural improvements — refinements to patterns, new abstractions, better TypeScript types. May require minor adjustments to code that extends those patterns. Breaking changes — rare, but when they happen they’ll be clearly marked in the announcement with a migration guide. Breaking changes are never shipped silently.

​
If you’ve diverged significantly

If you’ve been building for a while and the merge looks overwhelming, don’t panic. A few options: Cherry-pick specific commits — instead of merging everything, pick only the commits you want: 
git cherry-pick <commit-hash>
Ask for help — post in #help with your situation. If you’re on the Studio plan, this is exactly what the architecture call is for. Skip the update — you own the code. If an update doesn’t add value for your project right now, you don’t have to take it. Your existing codebase won’t break.

​
What’s next?

  • Support — Discord, bug reports, and how to reach me directly.
  • Getting started — back to the beginning if you need a fresh orientation.