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

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# GitHub

> Connect an app to a GitHub repository and sync code in both directions with the Base44 Apps API

<Note>
  The Apps API is in beta. Its endpoints and responses may change.
</Note>

These endpoints connect an app to a GitHub repository and keep the two in sync. Once connected, the repository is where the app's code lives. Base44 pushes each change to it, and you bring work done in GitHub back into the app. See [GitHub integration](/developers/app-code/local-development/github) for the same feature in the Base44 online app editor.

<Warning>
  Connecting a repository needs a workspace plan that includes the GitHub integration, and only the app's owner can do it.
</Warning>

## Connect a repo

Call [List GitHub organizations](/api-reference/list-github-organizations) to see where you can create the repository, then [Get GitHub organization policy](/api-reference/get-github-organization-policy) to check whether the workspace limits the choice. [Connect a GitHub repository](/api-reference/connect-a-github-repository) creates a new private repository and pushes the app's current code as the first commit. After it returns, read [Get GitHub connection](/api-reference/get-github-connection) and check `webhook_active`, since the webhook is the one step that can fail without failing the connection.

## Sync changes

* [Pull changes from GitHub](/api-reference/pull-changes-from-github) brings in new commits. If it reports a merge conflict, [Resolve GitHub sync conflicts](/api-reference/resolve-github-sync-conflicts) asks the AI to resolve it.
* [Push changes to GitHub](/api-reference/push-changes-to-github) pushes the latest saved version. Base44 pushes each saved version by itself, so use this when a push failed.
* [Turn automatic GitHub sync on or off](/api-reference/turn-automatic-github-sync-on-or-off) controls whether commits pushed from outside Base44 are pulled in automatically.

## Pull error codes

A failed pull is reported in the `error` field of the response, not as an HTTP error. [Pull changes from GitHub](/api-reference/pull-changes-from-github) returns it directly. [Reconnect a GitHub repository](/api-reference/reconnect-a-github-repository) returns it in `sync` when the pull after a reconnect fails. The `error_message` field holds a readable explanation.

| Code | What it means and what to do |
| - | - |
| `not_connected` | The app has no active GitHub connection. Connect a repository with [Connect a GitHub repository](/api-reference/connect-a-github-repository), or restore a disconnected one with [Reconnect a GitHub repository](/api-reference/reconnect-a-github-repository). |
| `no_installation` | The connection has no Base44 GitHub App installation. |
| `workspace_mismatch` | The connection belongs to a different workspace, which happens when an app moves. Disconnect the app with [Disconnect a GitHub repository](/api-reference/disconnect-a-github-repository). Then restore the repository with [Reconnect a GitHub repository](/api-reference/reconnect-a-github-repository) if the app's workspace has access to the GitHub account, or connect a new one with [Connect a GitHub repository](/api-reference/connect-a-github-repository). |
| `sync_in_progress` | Another sync or builder operation is running on the app. Wait for it to finish, then pull again. |
| `connection_error` | The connection is in an `error` or `revoked` state, usually because GitHub refused an earlier call. Reinstall the Base44 GitHub App on the repository's account, then read [Get GitHub connection](/api-reference/get-github-connection), which re-checks the installation. |
| `merge_conflict` | The repository's commits and the app's own changes touch the same lines. Hand it to [Resolve GitHub sync conflicts](/api-reference/resolve-github-sync-conflicts). |
| `sandbox_sync_failed` | Applying the commits failed, and it wasn't a conflict Base44 could capture. Pull again. |
| `rate_limit_low` | GitHub's request allowance for the connection is nearly used up, so Base44 didn't start the pull. Wait for it to reset. The `error_message` says how long. |
| `rate_limit_exceeded` | GitHub's request allowance ran out during the pull. Wait for it to reset, then pull again. |
| `github_api_error` | A GitHub call failed for another reason. The `error_message` says why. A refusal can also put the connection in an error state, which then returns `connection_error`. |
| `unexpected_error` | The pull failed for a reason Base44 didn't anticipate. Pull again. |

## Endpoints

### Connection

* [List GitHub organizations](/api-reference/list-github-organizations): List the GitHub accounts you can create the repository in.
* [Get GitHub organization policy](/api-reference/get-github-organization-policy): Check whether the workspace limits repositories to approved organizations.
* [Connect a GitHub repository](/api-reference/connect-a-github-repository): Create a private repository and connect the app to it.
* [Get GitHub connection](/api-reference/get-github-connection): Read the app's connection, if it has one.
* [Disconnect a GitHub repository](/api-reference/disconnect-a-github-repository): Disconnect the app, leaving the repository on GitHub.
* [Reconnect a GitHub repository](/api-reference/reconnect-a-github-repository): Reconnect an app to the repository it was disconnected from.

### Sync

* [Pull changes from GitHub](/api-reference/pull-changes-from-github): Pull new commits into the app.
* [Resolve GitHub sync conflicts](/api-reference/resolve-github-sync-conflicts): Ask the AI to resolve merge conflicts from a pull.
* [Push changes to GitHub](/api-reference/push-changes-to-github): Push the app's latest saved version.
* [Turn automatic GitHub sync on or off](/api-reference/turn-automatic-github-sync-on-or-off): Choose whether outside commits are pulled in automatically.
* [Import a GitHub branch](/api-reference/import-a-github-branch): Create a Base44 branch from an existing GitHub branch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.