GitHub integration

This article explains the GitHub Integration feature. By connecting GitHub repositories, you can sync code from selected repositories automatically or manually, allowing the AI to reference the code when answering questions or running workflows.

Prerequisites

Action	Required role
Connect or disconnect GitHub accounts for the organization	Admin / Owner
Choose or change the GitHub account used by this workspace	Admin / Owner
Select or change approved repositories	Workspace manager / Admin / Owner
Change the branch to sync	Workspace manager / Admin / Owner
Manual sync	Workspace manager / Admin / Owner
Change sync settings	Workspace manager / Admin / Owner

GitHub accounts are connected in Settings > Apps. After an admin or owner connects an account and approves repositories on GitHub, each workspace can select from that approved list.

Connecting a GitHub repository

GitHub repository connection screen

1. If your organization has not connected GitHub yet, ask an admin or owner to open Settings > Apps and connect a GitHub account.

2. On the workspace page, select Resources.

3. Select Codebase.

4. If more than one connected account is available and you are an admin or owner, choose the account in GitHub account.

5. Click Select repositories.

6. Select the repositories to sync from the approved list.

7. Click Save changes.

Selecting or changing repositories

After an admin or owner chooses the workspace's GitHub account, workspace managers can add or change the approved repositories to sync. If you unselect a repository, the corresponding codebase is automatically deleted.

Repository selection screen

1. On the workspace page, select Resources.

2. Select Codebase.

3. If you need a different GitHub account for this workspace, ask an admin or owner to change GitHub account first.

4. In the Selected repositories section, click Edit.

5. Select or unselect approved repositories to sync.

6. Click Save changes.

If the repository you need does not appear, ask an admin or owner to add it in Settings > Apps.

Changing the branch to sync

You can change the branch to sync for each connected repository. If no branch is specified, the repository's default branch is synced.

Branch selector

1. On the workspace page, select Resources.

2. Select Codebase.

3. In the Selected repositories section, click the button showing the current branch name on the target repository's row.

4. Select a branch from the list. You can filter by branch name using the search box.

Running manual sync

Manually update GitHub repository content to the latest state.

Manual sync button

1. On the workspace page, select Resources.

2. Select Codebase.

3. On the GitHub card, click Sync.

Changing sync settings

In addition to manual sync, you can configure sync triggered by push/commit events or scheduled sync at a specified cadence.

Sync settings dialog

1. On the workspace page, select Resources.

2. Select Codebase.

3. In the Sync settings section, click Configure.

4. Choose the sync timing.

   • Manual sync: Sync only when manually triggered.

   • Trigger sync on push/commit: Automatically sync when code is pushed to the selected branch.

   • Enable automatic sync: Sync periodically at the specified cadence and time. Choose a Frequency (Daily / Weekly / Monthly) and Time. For Weekly, also specify the Day of week; for Monthly, also specify the Day of month.

5. Click Save.

Disconnecting GitHub

Disconnecting GitHub removes the connected account for the entire organization. Every workspace that uses that account loses access to its selected repositories, and their synced codebases are deleted. If you only want to stop using one repository in a workspace, remove it from Selected repositories instead.

1. Open Settings > Apps.

2. Open the connected GitHub account you want to remove.

3. Click Disconnect.

4. Confirm the action.

Troubleshooting

GitHub integration errors

Situation	Cause	Resolution
The workspace says GitHub is not connected	No GitHub account is connected at the organization level	Ask an admin or owner to connect GitHub in Settings > Apps.
GitHub access was revoked appears on a codebase	The GitHub App was uninstalled, suspended, or can no longer see the connected account	The last successful sync stays available with a Stale label. Ask an admin or owner to reconnect GitHub from Settings > Apps, then run Sync again.
GitHub access to this repository was revoked appears	The repository was renamed, transferred, deleted, or removed from the GitHub App or approved list	The last successful sync stays readable with a Stale label. Ask an admin or owner to re-approve the repository or choose a different account, then select the repository again and run Sync.
Authentication from Connect GitHub fails	Insufficient GitHub account permissions, or access denied	Check your GitHub account permissions and try connecting again.
The request never reached GitHub appears	A proxy, firewall, or other network device answered instead of the GitHub API	The connection may not be revoked. Check outbound access to the GitHub API, review your network settings, and run Sync again.
"Failed to sync repository" appears	Network error or temporary GitHub API issue	Click Sync again to retry manual sync.
Message indicates that a sync is already in progress	Another sync is running	Wait for the current sync to complete and retry.
"Failed to load GitHub installations" appears	Failed to fetch GitHub integration data	Reload the page. If the issue persists, ask an admin or owner to reconnect GitHub from Settings > Apps.
"Failed to delete code archive" appears	An error occurred during deletion	Reload the page and try again.
"Failed to load branches" appears	Failed to fetch the repository's branch list	Reload the page. If the issue persists, disconnect GitHub and reconnect.
"Failed to update branch" appears	Network error or temporary server issue	Wait and try again.