> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting guide for connecting a GitHub repository to Maia

export const designer = "Designer";

export const maia = "Maia";

This page is a list of troubleshooting guidance in the event that you experience issues when connecting your GitHub repository to a {maia} project. Each scenario includes both an issue and a solution.

For basic connectivity issues, make sure the [Hybrid SaaS agents and Git repositories IP addresses](/docs/security/network-access-and-ip-allowlist-requirements#hybrid-saas-agents-and-git-repositories) are allowed on your repository.

***

## Authorization fails

Possible cause: {maia} can't reach GitHub.

Solution: If you receive an authorization error, refresh the page and try again. If the issue persists, either GitHub or {maia} may be experiencing an issue.

* [GitHub status page](https://www.githubstatus.com/)
* [Matillion status page](https://status.matillion.com/)

***

## Unable to retrieve repositories

Possible cause 1: {maia} app not installed in the user's organization.

Solution: Make sure the {maia} app is installed in the correct GitHub organization. Follow the steps at [Installing the {maia} app in GitHub](/docs/guides/installing-matillion-app-github-marketplace).

Possible cause 2: The {maia} app does not have access to the repository you wish to connect.

Solution: Visit `https://github.com/organizations/<your-org-name>/settings/installations` (replace `<your-org-name` with the org name in your GitHub URL) and click **Configure**. From here you can view a list of repositories that the {maia} app has access to. Confirm that the repository you're looking for is on the list. If it isn't, follow the steps at [Installing the {maia} app in GitHub](/docs/guides/installing-matillion-app-github-marketplace).

Possible cause 3: The {maia} app has access to the repository but the user does not.

Solution: Make sure your GitHub user has the correct repository role in the organization that the {maia} app is installed in. The user needs at least the `Write` role to the repository to use that repository with {maia}.

Read [Repository roles for organizations](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#repository-roles-for-organizations) to learn more about roles in GitHub.

Possible cause 4: The repository does not exist.

Solution: Visit `https://github.com/organizations/<your-org-name>/settings/installations` and click **Configure**. Here you can view the list of repositories that the {maia} app has access to. If no repositories are selected, create a repository in that organization first, and *then* create a project in {maia}.

Possible cause 5: You authorized with a different user that doesn't have access to the desired repository.

Solution: Follow the instructions in [Reconnecting your Git user account](/docs/guides/reconnecting-git-user-account) with the user that has access to the desired repository.

***

## Users can't see data pipelines in Designer

Possible cause 1: User does not have the correct repository role in GitHub.

Solution: Make sure your GitHub user has the correct repository role in the organization where the {maia} app is installed. You need at least the `Write` role to the repository to use that repository with {designer}. Read [Repository roles for organizations](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#repository-roles-for-organizations) to learn more.

Possible cause 2: GitHub repository does not have a default branch called `main`.

Solution: One of the [prerequisites](/docs/guides/connect-github-repository-prerequisites) to connect your GitHub repository to a project in {maia} is to have a default branch called `main`.

When you create a new repository and add a first commit, GitHub automatically creates a default branch named `main`. It is advised to not rename this branch.

<Note>
  When you enable the {maia} app in your organization, only the `main` branch from repository that you sync to your {maia} project will be synced. Other branches will be ignored.
</Note>

***

## Unable to push to GitHub repository

Possible cause: User has the correct Write repository role, but they have selected the "Keep my email addresses private" and "Block command line pushes that expose my email" checkboxes.

Solution: Navigate to your profile settings at [https://github.com/settings/emails](https://github.com/settings/emails) and clear the "Block command line pushes that expose my email" checkbox.

***

## Permission denied to access GitHub repository

Possible cause: User has clicked **Continue** on the GitHub SSO page instead of **Authorize**.

Solution: To reauthorize your GitHub connection:

1. Log in to your GitHub Account.

2. Click **Settings** → **Applications** and then choose the [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) tab. Click **Revoke** next to the **{maia} for Github** app.

   <Note>
     Make sure the **{maia} for Github** app is already installed.
   </Note>

3. Log out of your GitHub account.

4. Access {maia} and perform a Git action that interacts with the remote repository, such as **Pull remote changes**.

5. Return to GitHub, go through the authorization process until you get to the **Single Sign on** step. Click **Authorize**, and continue until this process is complete.

6. For GitHub only. Once you click **Authorize**, the browser tab will close and return you to {maia}. On successful authorization, confirm if you can see your account in the list of authorized accounts. Click **Continue** to close the dialog.

***

## Related pages

* [Prerequisites](/docs/guides/connect-github-repository-prerequisites)
* [Installing the {maia} app in the GitHub Marketplace](/docs/guides/installing-matillion-app-github-marketplace)