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

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

Create or Select Repo

  • New Repository: Natively creates a new repo for your project
  • Existing Repository: Select an existing empty repository
4

Sync

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. You don’t need to manually push changes.

​
Repository Structure

Your GitHub repository contains the complete Expo project: 
my-app/
├── app/                 # Screens (file-based routing)
├── components/          # Reusable components
├── utils/              # Helper functions
├── assets/             # Images, fonts
├── app.json            # Expo configuration
├── package.json        # Dependencies
├── tsconfig.json       # TypeScript config
└── README.md           # Auto-generated readme

​
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

npm install
3

Start Expo

npx expo start
4

Test on Device

Scan QR code with Expo Go app or run in simulator

​
Local Development Requirements

  • Node.js 18+
  • npm or yarn
  • Expo CLI (npx 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. Use environment variables instead.
Check the commit history to understand what the AI changed
Create branches for experimental features to avoid breaking main

​
Disconnecting GitHub

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

​
Troubleshooting

  • Check GitHub authorization is still valid
  • Verify repository exists and you have write access
  • Check for branch protection rules
  • 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