Connect a GitHub repository

Connecting a repository is one of three ways to add an app to a project, alongside creating a new app and importing existing code. An import copies your code into Draftbit. A connected app works in your repository itself: Draftbit keeps your files as they are, and saving in the builder commits straight to the branch you choose.

Connected apps get chat, code editing, and a preview when your app has one. There’s no migration step, and Draftbit doesn’t rewrite your project to fit its conventions.

Connect a repository

Open your project and click Connect repo next to Import app and Add app. You need the Editor role or higher.

First choose how Draftbit reaches your repository:

• GitHub App (recommended): Draftbit uses the Draftbit GitHub App, the same app used to import private repositories. There’s no token to create or renew.
• Access token: you paste a GitHub fine-grained personal access token.

Connect with the GitHub App

1. Click Connect GitHub. A GitHub window opens where you choose which account or organization to install the Draftbit GitHub App on, and which repositories it can see.
2. Pick the account, then search for and select the repository.
3. Check the Main branch (it starts as the repository’s default branch) and set the App folder if your app isn’t at the top of the repository.

To save your changes, the GitHub App needs the Contents: Read and write permission on the repository. If GitHub asks you to approve updated permissions for the app, approve them before you connect. To use a repository the app can’t see yet, click Add account to reopen GitHub and add the repository to the installation.

Connect with an access token

Fill in the repository details:

• Repository address: for example https://github.com/owner/repo.
• App folder: leave this empty when your app’s package.json is at the top of the repository. For a monorepo, give the folder that contains it, such as apps/mobile. Draftbit works only inside this folder.
• Main branch: the branch your saves commit to. Draftbit keeps your in-progress work on a separate working branch until you save.
• Fine-grained access token: a GitHub fine-grained personal access token (it starts with github_pat_). Give it access to only this repository, with Contents: Read and write. If your app changes GitHub Actions workflows, also grant Workflows: Read and write. If your organization uses SAML single sign-on, authorize the token for it. Classic tokens aren’t supported.

Finish connecting

Click Continue. Draftbit runs the same checks as an import, and also confirms it can reach the repository and branch and push to them. If the branch is protected, you’ll see a warning: saving fails unless the GitHub App or token is allowed to push to that branch.

Once the checks pass, name the app and click Connect repository. The app opens in the builder when it’s ready.

How connected apps look

On the project page, a connected app’s card has a dark left edge, a Connected repo label, the repository it works in, such as owner/repo/apps/mobile, and how it connects (via GitHub App or via token). That keeps connected apps easy to tell apart from apps that live in Draftbit.

Working in a connected repository

• Saving commits your changes to the main branch you chose. Because your code already lives on GitHub, the Export menu doesn’t offer GitHub Export for connected apps.
• Syncing: when someone pushes new commits to the main branch, click Sync in the top bar to bring them into your working branch. You need to sync before you can save. If the sync hits conflicts, the button changes to Resolve sync so you can work through them.
• Changing the connection: open the app card’s menu and choose Repository Connection (Editors and above) to update the repository, branch, app folder, or how the app connects. You can switch between the GitHub App and an access token at any time. Click Check Access to test it before saving. Changing the repository or branch rebuilds the app on a new working branch, and unsaved changes aren’t carried over. With a token, leave the token field empty to keep the current one.

When access stops working

If Draftbit loses access to the repository, the app’s card shows Repository access lost, and the app won’t open until the connection works again. Open Repository Connection to fix it. The dialog tells you what went wrong, such as an archived repository, a branch that no longer exists, or a token that can’t push.

• GitHub App: access stops when the app is uninstalled from the account, the repository is removed from the installation, or the installation hasn’t approved the permissions Draftbit needs. Reinstall the app or add the repository back on GitHub, then save the connection again. Removing Draftbit from an account in the GitHub account list, or disconnecting GitHub, also stops every app connected through it.
• Access token: access stops when the token expires, is revoked, or loses access to the repository. Token expires soon appears on the card in the week before the token’s expiration date. Paste a new token and save.

Limits

• One app per repository: a repository that’s already connected to another app can’t be connected again.
• The app folder needs its own package.json and lockfile. A repository that is itself a workspace root isn’t supported yet.
• The same frameworks as imports are supported. See What can be imported.