Skip to main content
When we release updates to Shipnative, you may want to incorporate them into your project. Since you own your codebase and likely have custom modifications, updates require a manual merge process.
Your app is yours. Unlike a dependency you update via npm, Shipnative is a starting point you’ve customized. Updates are applied by merging our changes with yours, not by replacing your code.

​
Choose Your Workflow

There are two main workflows for staying updated. We recommend the Upstream Remote workflow for most users.

Upstream Remote (Recommended)

Best for most users. Keep your own repo structure, pull updates when needed. Simpler setup, works immediately.

Fork-Based

Best if you want to contribute back. Fork the repo, sync periodically. Requires accepting org invitation first.
AspectUpstream RemoteFork-Based
Setup complexitySimple - just add a remoteRequires org invitation + fork
Can contribute PRsNoYes
Repo ownershipYour own repo from scratchFork of Shipnative
Recommended forMost usersContributors

​
Before Any Upgrade

  1. Commit all your current work - Ensure your working directory is clean
  2. Check the CHANGELOG - Review what changed and whether you need/want the updates
  3. Back up your branch - Create a backup branch before merging
# Ensure everything is committed
git status

# Create a backup branch
git checkout -b backup/pre-upgrade-$(date +%Y%m%d)
git checkout main  # or your primary branch
This is the simplest approach. You keep your own repo and pull updates from Shipnative when needed.

​
Initial Setup (One-Time)

After cloning Shipnative, set up your remotes: 
# Rename the original remote to 'upstream'
git remote rename origin upstream

# Add your own repo as 'origin'
git remote add origin https://github.com/YOUR_USERNAME/your-app.git

# Verify setup
git remote -v
# origin    https://github.com/YOUR_USERNAME/your-app.git (fetch)
# origin    https://github.com/YOUR_USERNAME/your-app.git (push)
# upstream  https://github.com/shipnativeapp/shipnative.git (fetch)
# upstream  https://github.com/shipnativeapp/shipnative.git (push)

# Push to your repo
git push -u origin main
Already disconnected the remote? No problem - just add it back:
git remote add upstream https://github.com/shipnativeapp/shipnative.git

​
Pulling Updates

When you want to incorporate Shipnative updates: 
# Fetch latest from Shipnative
git fetch upstream

# Create an upgrade branch (don't merge directly to main)
git checkout -b upgrade/shipnative-$(date +%Y%m%d)

# Merge upstream changes
git merge upstream/main --no-commit
The --no-commit flag lets you review changes before committing.

​
Resolve Conflicts

If there are conflicts: 
git status  # Shows conflicted files
For each conflicted file:
  1. Open the file and look for conflict markers (<<<<<<<, =======, >>>>>>>)
  2. Decide which changes to keep (yours, theirs, or a combination)
  3. Remove the conflict markers
  4. Stage the resolved file: git add <filename>

​
Complete the Upgrade

# After resolving conflicts and testing
git commit -m "Upgrade to Shipnative $(date +%Y%m%d)"

# Merge to main
git checkout main
git merge upgrade/shipnative-$(date +%Y%m%d)

# Push to your repo
git push origin main

​
Workflow 2: Fork-Based

Use this if you want to contribute changes back to Shipnative via pull requests.
Prerequisite: You must accept the organization invitation first. Check your GitHub notifications or email for an invite to join shipnativeapp. Once accepted, you can fork the private repo.

​
Initial Setup (One-Time)

  1. Accept org invitation - Check GitHub notifications
  2. Fork the repo - Go to https://github.com/shipnativeapp/shipnative and click “Fork”
  3. Clone your fork:
git clone https://github.com/YOUR_USERNAME/shipnative.git my-app
cd my-app

# Add upstream remote pointing to original
git remote add upstream https://github.com/shipnativeapp/shipnative.git

# Verify setup
git remote -v
# origin    https://github.com/YOUR_USERNAME/shipnative.git (fetch)
# origin    https://github.com/YOUR_USERNAME/shipnative.git (push)
# upstream  https://github.com/shipnativeapp/shipnative.git (fetch)
# upstream  https://github.com/shipnativeapp/shipnative.git (push)

​
Syncing Your Fork

When you want to incorporate Shipnative updates: 
# Fetch latest from original repo
git fetch upstream

# Create upgrade branch
git checkout -b upgrade/sync-$(date +%Y%m%d)

# Merge upstream changes
git merge upstream/main --no-commit

# Resolve conflicts, test, then commit
git commit -m "Sync with upstream $(date +%Y%m%d)"

# Merge to main and push to your fork
git checkout main
git merge upgrade/sync-$(date +%Y%m%d)
git push origin main

​
Contributing Back

If you fix a bug or add a feature others might benefit from: 
# Create a feature branch from latest upstream
git fetch upstream
git checkout -b fix/your-bugfix upstream/main

# Make your changes, commit
git add .
git commit -m "Fix: description of fix"

# Push to your fork
git push origin fix/your-bugfix

# Create PR on GitHub from your fork to shipnativeapp/shipnative

​
Additional Methods

​
Cherry-Pick Specific Changes

When you only want specific commits (e.g., a bug fix or new feature): 
git fetch upstream
git log upstream/main --oneline  # Find commit hashes

git checkout -b feature/specific-update
git cherry-pick abc1234  # Cherry-pick by commit hash
git cherry-pick def5678
If conflicts occur: 
# Resolve conflicts, then:
git cherry-pick --continue

​
Manual Copy

For small updates or when git conflicts are overwhelming:
  1. Check the CHANGELOG for what changed
  2. Browse the commit history to see file changes
  3. Manually copy the relevant code changes into your project
  4. Test thoroughly
This method is error-prone for large updates. Prefer git merge when possible.

​
Post-Upgrade Checklist

After any upgrade:
1

Install Dependencies

yarn install
New packages may have been added.
2

Check for New Environment Variables

Compare your .env with .env.example:
diff apps/app/.env apps/app/.env.example
Add any new variables.
3

Run Database Migrations (if applicable)

For Supabase:
supabase db push
For Convex:
npx convex dev
4

Rebuild Dev Client (if native changes)

If native code changed (new packages, config changes):
cd apps/app
yarn prebuild:clean
yarn ios  # or yarn android
5

Test Core Flows

  • Sign up / Sign in
  • Profile updates
  • Payments (in sandbox)
  • Push notifications

​
Handling Common Conflicts

​
app.json Conflicts

Keep your app name, bundle ID, and scheme. Accept new Expo SDK versions or plugin configurations: 
{
  "expo": {
    "name": "YOUR APP NAME",        // Keep yours
    "slug": "your-app-slug",        // Keep yours
    "version": "1.0.0",             // Keep yours
    "sdkVersion": "52.0.0",         // Accept theirs (usually)
    "ios": {
      "bundleIdentifier": "com.you.yourapp"  // Keep yours
    }
  }
}

​
package.json Conflicts

Generally accept the upstream dependency versions unless you have a specific reason to stay on an older version: 
# After resolving package.json
yarn install

​
Screen/Component Conflicts

If you’ve heavily modified a screen:
  1. Review what the upstream change does
  2. Decide if you need it
  3. If yes, manually integrate the logic into your version
  4. If no, keep your version

​
Staying Informed

CHANGELOG

All releases documented with migration notes

Discord

Announcements and upgrade help from the community

​
FAQ

Use Upstream Remote (recommended) unless you specifically want to contribute PRs back to Shipnative. It’s simpler to set up and works the same way for pulling updates.
There’s no fixed schedule. Check the CHANGELOG periodically (monthly is reasonable) and upgrade when you see changes relevant to your app - security fixes, features you want, or bug fixes you’ve encountered.
Yes. Each upgrade merges the latest changes regardless of how many versions you’ve skipped. However, larger gaps mean more potential conflicts.
Ask in Discord! Share the conflicted file and your use case, and we’ll help you work through it.
Yes! Just add the upstream remote again:
git remote add upstream https://github.com/shipnativeapp/shipnative.git
git fetch upstream
You need to accept your organization invitation first. Check your GitHub notifications or email for an invite to join shipnativeapp. Once you’re an org member, you can fork private repos.