> ## 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. 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.
This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.
## 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. 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.
This endpoint accepts a personal API key. Workspace API keys are
not authorized for it and are rejected with a 403.
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: >-
`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':
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: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
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:
type: string
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).
example: '58231904'
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
- installation_id
title: ConnectRepoRequest
description: Request to connect a repository.
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.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````