---
title: "Connect a GitHub repository"
method: POST
path: "/api/apps/{app_id}/github/connect"
---

# Connect a GitHub repository

`POST /api/apps/{app_id}/github/connect`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Creates a new private GitHub repository and connects the app to it.

Only the app's owner can connect a repository, and the workspace plan has to include the GitHub integration. Read [List GitHub organizations](/api-reference/list-github-organizations) for the `org_name` and `installation_id` to send.

The call holds the connection while it creates the repository, installs the sync webhook, and pushes the app's current code as the first commit, so it takes considerably longer than the other endpoints here. From then on the repository is where the app's code lives: Base44 pushes each change to it, and you bring work done in GitHub back with [Pull changes from GitHub](/api-reference/pull-changes-from-github).

The repository must not exist yet. Send a `repo_name` of 1 to 100 characters made of letters, digits, hyphens, underscores or periods, starting and ending with a letter or digit. An app that already has a connection can't connect again, and disconnecting one happens in the builder rather than through this API.

If that first push fails, Base44 undoes the connection, but the repository it already created stays on GitHub. Delete it there or send a different `repo_name` before you retry, or the retry fails on the repository already existing.

The webhook is best effort. Read `webhook_active` from [Get GitHub connection](/api-reference/get-github-connection) afterwards: while it is `false`, GitHub isn't telling Base44 about pushes, so bring commits in with [Pull changes from GitHub](/api-reference/pull-changes-from-github) rather than waiting for them to arrive on their own.

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

## Path parameters

- `app_id` string, required — ID of the app to connect to a GitHub repository.

## Request body

- ConnectRepoRequest — Request to connect a repository.
  - `org_name` string, required — GitHub username or organization to create the repository under, as returned in `login` by [List GitHub organizations](/api-reference/list-github-organizations).
  - `repo_name` string, required — Name for the new repository. 1 to 100 characters made of letters, digits, hyphens, underscores or periods, starting and ending with a letter or digit, and it must not already exist on the account.
  - `installation_id` string, required — ID of the Base44 GitHub App installation on that account, as returned in `installation_id` by [List GitHub organizations](/api-reference/list-github-organizations).
  - `description` string, nullable — Description for the new repository. Defaults to the app's name.

## Response `200`

The repository that was created and connected.

- RepositoryConnectionResponse — Result of connecting a repository.
  - `connection_id` string, required — ID of the connection Base44 stored for this app.
  - `repo_url` string, required — URL of the repository on GitHub.
  - `repo_full_name` string, required — Full repository name, as `owner/repo`.
  - `clone_urls` CloneUrls, required — Repository clone URLs in different formats.
    - `https` string, required — URL to clone the repository over HTTPS.
    - `ssh` string, required — URL to clone the repository over SSH.
    - `gh_cli` string, required — Ready-to-run GitHub CLI clone command.
  - `default_branch` string, required — Default branch of the new repository. Base44 pushes the app's code to this branch.

## Other responses

- `400` — `repo_name` is invalid, the repository already exists, the app is already connected, your GitHub account isn't connected to Base44, or the GitHub App on this account covers selected repositories only.
- `401` — Missing or invalid credentials.
- `402` — Your workspace plan doesn't include the GitHub integration.
- `403` — You aren't the app's owner, the app's workspace doesn't approve this GitHub organization, or you used a workspace API key.
- `404` — App not found.
- `409` — The app is busy with another operation. Wait for it to finish and try again.
- `422` — Validation Error

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/idealspot/base44-app-management-api/revisions/31ef75eb64ab/schema)