> ## 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.
# Connect a GitHub repository
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
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. An app that already has a connection can't connect again, and this API can't disconnect one. You do that in the Base44 online app editor.
The call creates the repository, installs the webhook that tells Base44 about new commits, and pushes the app's current code as the first commit. The response comes back only after all of that finishes. The webhook is the one step that can fail without failing the connection, so check `webhook_active` in [Get GitHub connection](/api-reference/get-github-connection) afterwards.
If any of the rest fails, Base44 undoes the connection but leaves the repository it already created on GitHub. Delete that repository or send a different `repo_name` before you retry. Check [Get GitHub connection](/api-reference/get-github-connection) first, because a failure late in the call can leave the connection in place.
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).
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/github/connect
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/github/connect:
post:
summary: Connect a GitHub repository
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
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. An app that already has a
connection can't connect again, and this API can't disconnect one. You
do that in the Base44 online app editor.
The call creates the repository, installs the webhook that tells Base44
about new commits, and pushes the app's current code as the first
commit. The response comes back only after all of that finishes. The
webhook is the one step that can fail without failing the connection, so
check `webhook_active` in [Get GitHub
connection](/api-reference/get-github-connection) afterwards.
If any of the rest fails, Base44 undoes the connection but leaves the
repository it already created on GitHub. Delete that repository or send
a different `repo_name` before you retry. Check [Get GitHub
connection](/api-reference/get-github-connection) first, because a
failure late in the call can leave the connection in place.
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).
operationId: connect_repository_api_apps__app_id__github_connect_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app to connect to a GitHub repository.
title: App Id
description: ID of the app to connect to a GitHub repository.
example: 6820f3a4e7b91d003c45a1f2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectRepoRequest'
responses:
'200':
description: The repository that was created and connected.
content:
application/json:
schema:
$ref: '#/components/schemas/RepositoryConnectionResponse'
'400':
description: >-
The `repo_name` is invalid, the repository already exists, the app
is already connected, your GitHub account isn't connected to Base44,
the `installation_id` isn't one you can use on that account, or the
GitHub App on this account covers selected repositories only.
'401':
description: Missing or invalid credentials.
'402':
description: Your workspace plan doesn't include the GitHub integration.
'403':
description: >-
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':
description: App not found.
'409':
description: >-
The app is busy with another operation. Wait for it to finish and
try again.
'422':
description: >-
The request body is missing a required field, or one of its values
has the wrong type.
components:
schemas:
ConnectRepoRequest:
properties:
org_name:
type: string
title: Org Name
description: >-
GitHub username or organization to create the repository under, as
returned in `login` by [List GitHub
organizations](/api-reference/list-github-organizations).
example: base44
repo_name:
type: string
title: Repo Name
description: >-
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.
example: lead-tracker
installation_id:
anyOf:
- type: string
- type: 'null'
title: Installation Id
description: >-
ID of the Base44 GitHub App installation on that account, as
returned in `installation_id` by [List GitHub
organizations](/api-reference/list-github-organizations). Provide
either this or `workspace_installation_id`.
example: '58231904'
workspace_installation_id:
anyOf:
- type: string
- type: 'null'
title: Workspace Installation Id
description: >-
ID of a GitHub installation connected to the app's workspace, as
returned by the workspace installations listing. Provide either this
or `installation_id`.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Description for the new repository. Defaults to the app's name.
example: Sales lead tracker
type: object
required:
- org_name
- repo_name
title: ConnectRepoRequest
description: >-
Request to connect a repository.
Exactly one of `installation_id` or `workspace_installation_id` must be
provided.
RepositoryConnectionResponse:
properties:
connection_id:
type: string
title: Connection Id
description: ID of the connection Base44 stored for this app.
example: 6890b1c4f2a7e3105d8a4472
repo_url:
type: string
title: Repo Url
description: URL of the repository on GitHub.
example: https://github.com/base44/lead-tracker
repo_full_name:
type: string
title: Repo Full Name
description: Full repository name, as `owner/repo`.
example: base44/lead-tracker
clone_urls:
$ref: '#/components/schemas/CloneUrls'
description: URLs and CLI command for cloning the new repository.
default_branch:
type: string
title: Default Branch
description: >-
Default branch of the new repository. Base44 pushes the app's code
to this branch.
example: main
type: object
required:
- connection_id
- repo_url
- repo_full_name
- clone_urls
- default_branch
title: RepositoryConnectionResponse
description: Result of connecting a repository.
CloneUrls:
properties:
https:
type: string
title: Https
description: URL to clone the repository over HTTPS.
example: https://github.com/base44/lead-tracker.git
ssh:
type: string
title: Ssh
description: URL to clone the repository over SSH.
example: git@github.com:base44/lead-tracker.git
gh_cli:
type: string
title: Gh Cli
description: Ready-to-run GitHub CLI clone command.
example: gh repo clone base44/lead-tracker
type: object
required:
- https
- ssh
- gh_cli
title: CloneUrls
description: Repository clone URLs in different formats.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````