> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration

> Sync your code to GitHub for version control and collaboration

# GitHub Integration

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

## Why Connect GitHub

<CardGroup cols={2}>
  <Card title="Version Control" icon="code-branch">
    Full Git history outside of Newly
  </Card>

  <Card title="Collaboration" icon="users">
    Work with other developers on your code
  </Card>

  <Card title="Code Backup" icon="cloud-arrow-up">
    Your code is safe in your own repository
  </Card>

  <Card title="Local Development" icon="laptop-code">
    Clone and run your project locally
  </Card>
</CardGroup>

## Connecting GitHub

<Steps>
  <Step title="Open GitHub Settings">
    Click **More** → look for the GitHub button in the menu
  </Step>

  <Step title="Authorize Newly GitHub App">
    Click **Connect GitHub Account** and install the Newly App on your GitHub account.
    Installing the App does **not** create any repository on its own — it just
    grants Newly permission to create or connect one later.
  </Step>

  <Step title="Choose Create New or Use Existing">
    After install, pick one of:

    * **Create New** — Newly creates a fresh repository under your account (public or private).
    * **Use Existing** — paste a GitHub HTTPS clone URL of a repo you already have access to.
  </Step>

  <Step title="Your code syncs automatically">
    Once a repo is connected, Newly pushes your project to it and keeps it in sync.
  </Step>
</Steps>

## Automatic Syncing

Once connected, Newly automatically:

* **Pushes on commit** - Every change is synced to GitHub
* **Preserves history** - All commit messages are kept
* **Handles conflicts** - AI changes are cleanly merged

<Note>
  Syncing happens automatically when the AI writes code. You don't need to manually push changes or ask the AI to push.
</Note>

## Working Locally

Clone and run your project locally:

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/yourusername/your-app.git
    cd your-app
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Start Expo">
    ```bash theme={null}
    pnpx expo start --tunnel
    ```
  </Step>

  <Step title="Test on Device">
    Scan QR code with Expo Go app or run in simulator
  </Step>
</Steps>

### 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:

<Steps>
  <Step title="Newly for Design">
    Use Newly to prototype and build features quickly
  </Step>

  <Step title="GitHub for Collaboration">
    Developers clone the repo and make changes locally
  </Step>

  <Step title="Pull Requests">
    Review changes through GitHub PRs
  </Step>

  <Step title="Merge & Sync">
    Merged changes sync back to Newly
  </Step>
</Steps>

## Two-Way Sync

Newly supports syncing changes made outside of Newly:

<Note>
  When you push changes to GitHub from your local machine or via PR, those changes will be synced back to your Newly project.
</Note>

### Handling External Changes

1. Push changes to the `main` branch on GitHub
2. Newly 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

<AccordionGroup>
  <Accordion title="Use meaningful commit messages">
    The AI generates descriptive commit messages, but for local changes, use clear messages like "Add checkout screen" or "Fix navigation bug"
  </Accordion>

  <Accordion title="Don't commit secrets">
    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.
  </Accordion>

  <Accordion title="Review AI changes">
    Check the commit history to understand what the AI changed
  </Accordion>
</AccordionGroup>

## Disconnecting GitHub

The GitHub panel exposes three separate actions so you can stop at whichever level you need.

### When a repository is connected

<CardGroup cols={2}>
  <Card title="Disconnect Repo">
    Unlinks this project from its GitHub repository. The Newly GitHub App stays installed on your account and the repository stays on GitHub untouched — only this project stops syncing to it. You can reconnect the same repo or link a different one immediately.
  </Card>

  <Card title="Delete Repo">
    Same as **Disconnect Repo**, plus deletes the repository from GitHub itself. Your code is still safe in Newly's storage. The GitHub App stays installed.
  </Card>
</CardGroup>

### When no repository is connected

Once you've disconnected or deleted the repo, a third option appears at the bottom of the GitHub panel:

<Card title="Disconnect GitHub">
  Fully removes the Newly GitHub App from your GitHub account. This revokes Newly's access token, uninstalls the App, and clears every project's GitHub link. After this you're back to the **Connect GitHub Account** state.
</Card>

<Note>
  You can also uninstall the Newly App directly from
  [github.com/settings/installations](https://github.com/settings/installations) —
  Newly detects the uninstall automatically and updates the UI the next time
  you return to the tab.
</Note>

<Warning>
  None of these actions delete your code from Newly. Your project continues
  to work; it just stops syncing to GitHub until you connect a repo again.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sync Failed">
    * 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.
  </Accordion>

  <Accordion title="Conflicts">
    * Newly uses force push for AI changes
    * If you have local changes, pull before making changes in Newly
  </Accordion>

  <Accordion title="Missing Files">
    * Some files like `.env` are intentionally excluded
    * Check `.gitignore` for excluded patterns
  </Accordion>
</AccordionGroup>

## Private vs Public Repositories

You can choose either:

| Type    | Best For                              |
| ------- | ------------------------------------- |
| Private | Commercial projects, proprietary code |
| Public  | Open source projects, portfolios      |

<Tip>
  GitHub offers free private repositories, so there's no cost for keeping your code private.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Learn to edit code directly
  </Card>

  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Deploy your app to stores
  </Card>
</CardGroup>