> ## 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.
# Using Base Code
> Make changes to an existing GitHub codebase with the AI chat in Base Code, preview them on a branch, then get them reviewed and merged through pull requests.
[Base Code](https://base44.com/base-code) gives your team a shared cloud environment for an existing codebase without setting up a local development environment. Use the AI chat to make changes on branches, preview your work, and open pull requests for review. GitHub stays the source of truth.
**Before you begin:**
* Your project must be a web or full-stack project in a GitHub repository.
* You need an Editor role or higher in the workspace.
* You need to connect a GitHub account during setup.
***
## Setting up Base Code
Connect a GitHub repository to make changes with the AI chat in Base Code. If your GitHub account is already connected, continue to [choosing a repository](#choosing-a-repository).
### Connecting your GitHub account
Base Code works directly in your GitHub repositories, so it needs access to the ones you want to work on.
**To connect your account:**
1. Go to [Base Code](https://app.base44.com/base-code).
2. Click **Connect GitHub**.
3. Sign in to GitHub if prompted, then authorize **Base44 Builder**.
4. Select the GitHub account or organization, then follow the prompts to install or configure **Base44 Builder** and give it repository access.
### Choosing a repository
Pick the codebase you want to work on, from your own repositories or a copy of one you can't push to.
**To choose a repository from your account:**
1. In [Base Code](https://app.base44.com/base-code), click **View more**.
2. Select a repository.
3. Under **Branch**, keep the selected branch or select another.
4. Click **Connect**.
**To choose a repository by pasting a link:**
1. In [Base Code](https://app.base44.com/base-code), click **View more**.
2. Click **Paste a link**.
3. Paste the GitHub repository URL.
4. Continue based on your access:
* **You have write access:** Keep or change the selected **Branch**, then click **Connect**.
* **You don't have write access:** Under **Your copy on GitHub**, keep or change the suggested name. Select **Fork (public)** and click **Fork and connect**, or select **Private copy** and click **Copy and connect**. Your pull requests target your fork or copy, not the original repository.
**Other ways to open a repository:**
* **Open a listed repository:** Select it on the Base Code page, then click **Open in Base**. It opens on its default branch.
* **Connect another repository:** Click the repository drop-down in the sidebar, then click **Add repository**. On mobile, the repository drop-down on the Base Code page calls it **Add new repository**. Both open **Connect your repository**.
***
## Working on your project
Use the AI chat to make changes to your connected repository and test them in a development preview. As you chat, Base Code commits and pushes your changes to your working branch on GitHub.
Base Code provides a development preview, not production hosting. To release your changes or connect a custom domain, use your project's existing deployment process and hosting provider.
### Making your first change
Base Code starts a new branch from your first request and names it for you, so your change stays separate until you open a pull request. To keep working on an existing GitHub branch, [import it](#importing-a-branch-from-github).
**To make your first change:**
1. Go to [Base Code](https://app.base44.com/base-code).
2. (Optional) If a drop-down appears next to **Create new branch**, select the branch to start from.
3. In the prompt box, describe the change you want to make. For example:
```text theme={null}
Add a dark mode toggle to the settings page,
and remember the choice between visits.
```
4. Click **Create branch** to open the new branch and start making changes.
5. Review the change in **Preview**, then ask the AI chat for any adjustments.
### Reviewing your changes
Check exactly what changed before you ask anyone to review it.
**To review your changes:**
1. Open the changes you want to check:
* **One reply's changes:** Use the file list below that reply in the AI chat.
* **Every change on the branch:** Click **Create PR** at the top of the editor, or click the PR number if one already exists.
2. Click a file name to see its diff, with the lines added and removed.
### Reverting a file
Undo the changes you don't want in a file, with the revert saved as a new commit on your branch.
Reverting a file undoes all its committed changes on the branch, not just the changes from one reply.
**To revert a file:**
1. Click the revert icon next to the file in either file list, including an open pull request's.
2. Check that the right file appears in **Revert branch changes?**, then click **Revert**.
***
## Managing branches
Branches let you work on several changes at once without them affecting each other. Each branch has its own development environment in Base Code and its own pull request.
The branch sidebar is available on desktop. On mobile, use the branch drop-down.
### Working from the sidebar
See where each of your branches stands and go straight to the one that needs you.
**Your branches** in the sidebar lists the branches you created. Merged branches stay in the list, so you can still read their chats.
Each branch has a status icon. Hover over it to see the label, with the pull request number when there is one.
| What the icon shows | When you see it |
| - | - |
| Needs you | **Conflicts**, **Failed checks**, or **Changes requested** |
| On hold | **CI running** or **Review pending** |
| Nothing blocking | **Open** or **Approved** |
| Done | **Merged** |
| Not in review yet | **Draft**: you haven't opened a pull request for this branch, or the one you opened is still a draft on GitHub |
While the AI is building, the icon is replaced by **Working**, and by **Merging** while a merge runs. A dot on the right of a branch means the AI finished there and you haven't opened it since.
To open a branch, click it under **Your branches**. You can also click the branch drop-down above the AI chat and select a branch.
### Organizing your branches
Keep the branches you're focused on within reach and bring the ones that need you to the top.
**To pin a branch:**
1. Hover over the branch in the sidebar, then click its options icon .
2. Click **Pin**.
Pinned branches sit at the top of **Your branches**, above your groups. To unpin one, click **Unpin** in the same menu.
**To group branches:**
1. Click the **New group** icon next to **Your branches**.
2. Enter a **Group name**, then click **Create group**.
3. Drag a branch onto the group, or click the branch's options icon , click **Move to group**, then select the group.
To take a branch back out, drag it onto **Your branches**, or click its options icon , click **Move to group**, then click **Remove from group**. A group's own options icon has **Rename group** and **Delete group**.
**To sort branches:**
1. Click the **Sort branches** icon next to **Your branches**.
2. Under **Sort by**, select one of the following:
* **Priority:** Branches that need you first, then the ones on hold.
* **Last updated:** Most recently worked on first. This is the default.
* **Manual order:** The order you arranged by dragging.
**Arranging branches by hand:** Drag a branch to put it where you want it. The list switches to **Manual order** and keeps your arrangement until you sort it another way. You can also drag groups to reorder them.
### Creating branches
Start each new change on its own branch, from your default branch or from another branch you're working on.
**To create a branch from the sidebar:**
1. Click **New branch** in the sidebar.
2. Describe your change in the AI chat and send the message.
The sidebar names the branch for you and starts it from your repository's default branch. To start from another branch, use the branch drop-down instead.
**To create a branch from the branch drop-down:**
1. Click the branch drop-down above the AI chat.
2. Click **Create new branch**.
3. Select the starting branch from the drop-down next to **Start from**.
4. Describe your change in the AI chat and send the message.
### Importing a branch from GitHub
Import an existing GitHub branch to keep working on it in Base Code. Your changes are committed and pushed to that branch.
**To import a branch:**
1. Click the branch drop-down above the AI chat.
2. Click **Import from GitHub**.
3. Select the branch.
4. Click **Import**.
### Deleting a branch
Clear out branches you're done with, along with their chats, while the branches stay on GitHub.
**To delete a branch:**
1. Open the branch's menu in one of these places:
* In the sidebar, hover over the branch, then click its options icon .
* In the branch drop-down above the AI chat, click **More actions** next to the branch.
2. Click **Delete**.
3. Click **Delete branch** to confirm.
***
## Working with pull requests
Get your changes reviewed and merged through pull requests on GitHub.
Base Code always uses your own GitHub connection, whatever your workspace sets for its other apps. Your GitHub account needs to be connected and have write access to the repository. Base44 opens pull requests from your account. Each commit from the AI chat lists you as the author and `base44-builder[bot]` as co-author.
### Opening a pull request
After testing your changes, open a pull request for review.
Your pull request targets the branch your working branch was created from. The AI chat writes the title and description from your conversation and committed changes.
**To open a pull request from the top of the editor:**
1. Click **Create PR** at the top of the editor.
2. Review the changed files in **Create pull request**.
3. Click **Continue in builder**.
4. Review and send the prefilled message in the AI chat.
**Opening a pull request from the branch drop-down:** The drop-down opens a shorter form for the title and description, without the file review.
### Tracking your pull requests
Track the progress of your open pull requests and see which ones need your attention.
**To track your pull requests:**
1. Go to [Base Code](https://app.base44.com/base-code).
2. Under **Your open PRs**, choose what you want to do:
* **Open a pull request:** Click its PR number to open it on GitHub, or click its title to open its branch in Base Code.
* **Filter by status:** Click the filter, then select **All**, **In review**, **Conflicts**, or **Open**.
* **Find a pull request:** Click the search icon and enter its title or number.
* **Sort pull requests:** Click **Sort** to reverse the order by pull request number.
* **Draft:** It's still a draft on GitHub.
* **Open:** No reviewer yet, and nothing is blocking it.
* **In review:** A reviewer is assigned or has requested changes.
* **Approved:** A reviewer approved it.
* **Conflicts:** Your branch has [conflicts to resolve](#resolving-branch-conflicts) with its base branch.
### Resolving branch conflicts
If your pull request has conflicts, the AI chat can resolve them for you. Resolving conflicts merges the pull request's base branch into your working branch.
**To resolve conflicts:**
1. Click **Resolve conflicts** above the prompt box.
2. Review and test the changes the AI makes, especially where both branches changed the same feature.
### Answering review comments
Use the AI chat to address feedback on your pull request.
**To answer review comments:**
1. Ask the AI chat to list unresolved comments on your pull request. It includes the file and line for each thread.
2. Tell it which comments to address and what to change.
3. Review the proposed changes and replies before asking it to post.
4. Ask the AI chat separately to resolve a thread when you're ready.
***
## Adding secrets
Give your project the API keys and other credentials it needs without putting them in your repository.
The AI chat prompts you when a secret is required. Secrets are encrypted, shared across branches and kept when your environment rebuilds.
Changes and removals apply automatically to running branches. Inactive branches pick them up when you next open them.
**To add a secret:**
1. Click **Dashboard** at the top of the editor.
2. Click **Secrets**.
3. Click **Add Secret**.
4. Enter the **Secret Name** and **Secret Value**, then click **Add Secret**.
**Adding secrets in bulk:** Click **Import .env**, then upload or paste your file. Each `KEY=VALUE` line becomes a secret. An existing secret with the same name is overwritten.
***
## Collaborating with teammates
Your team can contribute to the same project and review each other's changes through pull requests.
Anyone with an Editor role or higher in the workspace can open an existing Base Code project without a separate app invitation. To invite someone outside your workspace, [add them as a collaborator](/Setting-up-your-app/Managing-access#working-with-collaborators) from the app editor.
***
## FAQs
Base Code works with web and full-stack projects. If you're building your app in Base44, keep building it in the app editor, and use the [GitHub integration](/developers/app-code/local-development/github) to sync it with a repository.
Base Code checks the project at the root of your repository. That project must be a web or full-stack project. A mobile app in a subfolder is fine as long as the root project qualifies.
On the Base Code page, click **View more**, or click **Add repository** in the sidebar's repository drop-down, to open **Connect your repository**. If your repository is still missing, give Base44 access to it on GitHub.
**To update repository access:**
1. On GitHub, give **Base44 Builder** access to the repository.
2. Reopen **Connect your repository** in Base Code.
Your workspace doesn't allow repositories from this GitHub organization. Ask someone who manages your workspace's GitHub settings to check that the organization is connected and **Allowed** under **Build tools** > **GitHub**, then try again.
If you only have read access, [connect a fork or private copy](#paste-a-link) instead. When your workspace limits repositories to approved organizations, you need write access to a repository in one of them.
Workspace settings control who can connect GitHub organizations and which organizations are available for new apps. Anyone in the workspace can use an organization that is already connected. This only controls who can add a new one.
**To manage GitHub organizations:**
1. Go to your workspace settings.
2. Under **Build tools**, click **GitHub**.
3. Choose what you want to do:
* **Choose who can connect organizations:** Under **Who can connect organizations**, select who can add an organization.
* **Filter organizations:** In **Connected organizations**, use the filter to show **All**, **Active**, or **Disconnected** organizations.
* **Make an organization available for new apps:** Under **Connected organizations**, use **Allowed** to control which organizations are available. Changing **Allowed** doesn't affect apps already using that organization.
* **Disconnect an organization:** Click the actions icon next to the organization, click **Disconnect organization**, then click **Disconnect**.
Disconnecting stops apps tied to that organization's workspace connection from syncing with GitHub. The confirmation lists the affected apps. **Base44 Builder** stays installed on GitHub, so you can reconnect the organization.
Yes. Base Code uses **Auto mode** by default to choose an AI model for each request.
**To choose an AI model:**
1. Click the model at the bottom of the AI chat.
2. Select the model you want to work with.
For more details, see [choosing an AI model](/Building-your-app/AI-chat-modes#choosing-your-model).
Your GitHub account must be connected and have write access to the repository. Otherwise, the project shows a **Read only** badge. You can discuss the project in the AI chat and switch branches, but you can't make changes or create a branch.
**To connect your GitHub account:**
1. Open the project.
2. In the **Connect your GitHub account** banner, click **Connect account**.
3. Authorize **Base44 Builder** on GitHub.
If you see **GitHub write access required**, your account is connected but lacks write access. Ask a repository admin to grant it, then click **Recheck permissions**.
When you return to Base Code, your project environment starts back up so you can continue working. If your environment needs rebuilding, Base Code uses the latest commit on your GitHub branch. Ask the AI chat to confirm your latest changes are on that branch before you leave.
Yes. Ask the AI chat to add the code using your project's own stack.
Connecting a repository doesn't automatically add or configure Base44 entities, login, or the SDK. Your project keeps its existing database, authentication, and routing.
For a new database or service, [add its connection string or API key as a secret](#adding-secrets).
If setup changes are required and you connected the default branch, Base Code creates a setup branch and commits them there. Its pull request targets the branch you connected. If you connected another branch, Base Code commits any setup changes directly to that branch.
To include unmerged setup changes in a new branch, [start from the branch containing those changes](#creating-branches).
After you open a pull request, new changes on your working branch are added to it, and GitHub runs your repository's configured checks.
Merge your pull request on GitHub, or ask the AI chat to merge it.
Base44 needs permission to open pull requests in your repository. If prompted, click **Review permissions on GitHub**. An owner of the GitHub account or organization that owns the repository needs to approve the requested access. Once approved, return to Base Code and try again.
See Base44's [Privacy Policy](https://base44.com/privacy-policy) for information about how personal information is collected and used. For information about AI model training and your data controls, see [Privacy and security](/Community-and-support/Privacy-and-security).
You can apply a coupon before or after connecting a repository.
Each coupon code applies to up to 10 people in your workspace.
**To apply a coupon:**
1. Go to [Base Code](https://app.base44.com/base-code).
2. Enter your coupon code:
* **Before connecting a repository:** Click **Have a coupon?** at the top right, then enter your code in the dialog.
* **After connecting a repository:** Enter your code in the field under **Have a coupon?**.
3. Click **Apply**.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.