Skip to main content

​
GitHub Integration

Connect your Natively project to GitHub to sync code, collaborate with developers, and maintain a backup of your project.

​
Why Connect GitHub

Version Control

Full Git history outside of Natively

Collaboration

Work with other developers on your code

Code Backup

Your code is safe in your own repository

Local Development

Clone and run your project locally

​
Connecting GitHub

1

Open GitHub Settings

Click More → look for the GitHub button in the menu
2

Authorize Natively Github App

Click “Connect GitHub” and authorize Natively to access your repositories
3

Create Repo

  • New Repository: Natively creates a new repo for your project
4

Press button again to Open Github Repo

Your code is pushed to the repository automatically

​
Automatic Syncing

Once connected, Natively automatically:
  • Pushes on commit - Every change is synced to GitHub
  • Preserves history - All commit messages are kept
  • Handles conflicts - AI changes are cleanly merged
Syncing happens automatically when the AI writes code. You don’t need to manually push changes or ask the AI to push.

​
Working Locally

Clone and run your project locally:
1

Clone Repository

git clone https://github.com/yourusername/your-app.git
cd your-app
2

Install Dependencies

pnpm install
3

Start Expo

pnpx expo start --tunnel
4

Test on Device

Scan QR code with Expo Go app or run in simulator

​
Local Development Requirements

  • Node.js 18+
  • pnpm
  • Expo CLI (pnpx expo)
  • iOS Simulator (Mac) or Android Emulator (optional)

​
Collaborating with Developers

​
Adding Collaborators

  1. Go to your repository on GitHub
  2. Settings → Collaborators
  3. Add team members by username or email

​
Development Workflow

For teams, we recommend:
1

Natively for Design

Use Natively to prototype and build features quickly
2

GitHub for Collaboration

Developers clone the repo and make changes locally
3

Pull Requests

Review changes through GitHub PRs
4

Merge & Sync

Merged changes sync back to Natively

​
Two-Way Sync

Natively supports syncing changes made outside of Natively:
When you push changes to GitHub from your local machine or via PR, those changes will be synced back to your Natively project.

​
Handling External Changes

  1. Push changes to the main branch on GitHub
  2. Natively detects the changes on next project open
  3. Your project is updated with the external changes
  4. AI has context of the new code

​
Best Practices

The AI generates descriptive commit messages, but for local changes, use clear messages like “Add checkout screen” or “Fix navigation bug”
Never commit API keys or passwords. Put secrets on the backend via “Secrets” for Liquid Backend. Commiting secrets will stop the Github connection to work.
Check the commit history to understand what the AI changed

​
Disconnecting GitHub

If you need to disconnect:
  1. Go to GitHub → Settings → Applications → Authorized Apps
  2. Find Natively and revoke access
Disconnecting doesn’t delete your code from GitHub. Your repository remains intact.

​
Troubleshooting

  • Check GitHub App authorization is still valid
  • Verify repository exists and you have write access
  • Check for branch protection rules
  • Verify you have no secrets pushed and that chat_history.json is in .gitignore as it may contain pre-signed urls that Github thinks are secrets.
  • Natively uses force push for AI changes
  • If you have local changes, pull before making changes in Natively
  • Some files like .env are intentionally excluded
  • Check .gitignore for excluded patterns

​
Private vs Public Repositories

You can choose either:
TypeBest For
PrivateCommercial projects, proprietary code
PublicOpen source projects, portfolios
GitHub offers free private repositories, so there’s no cost for keeping your code private.

​
Next Steps

Code Editor

Learn to edit code directly

Deployment

Deploy your app to stores