> ## 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.

# Prerequisites for connecting to a GitHub repository

export const maia_0 = undefined

export const designer = "Designer";

export const maia = "Maia";

<Info>
  This feature is available to customers on specific editions. Visit the {maia_0} [Pricing](https://www.maia.ai/pricing) page to learn more about each edition.
</Info>

Connecting a GitHub repository to {maia} is a multi-step process with certain prerequisite actions. Although it's possible to perform some of these actions in different orders, the order of steps outlined here will ensure the simplest and smoothest connection process.

***

## 1 - Create a new GitHub repository

In the GitHub organization where you wish to install the {maia} app, create a new repository. Initialize the repository by adding a README file. This will automatically set `main` as the default branch.

<Note>
  * A branch called `main` is required, but it does not have to be the default branch.
  * We recommend that you use your repository's README file to describe the purpose of the repository and the pipelines developed therein.
</Note>

<Warning>
  Matillion strongly recommends that you use the new repository that you created and intend to connect to {maia} solely for the purpose of developing your {designer} pipelines.
</Warning>

### Want to use an existing repo?

If you already have an existing GitHub repository, you can connect that repository to your {maia} project, too. Once you complete the authorization between GitHub and {maia}, you'll see your existing repositories in the **Available repositories** drop-down menu when you [add a new project](/docs/guides/projects#add-a-new-project). If you choose an existing repository, only the `main` branch is synced to your {maia} project and made available in the [Branches](/docs/guides/branches) tab. Any other branches in the repository are ignored.

***

## 2 - Install the Maia app in your GitHub organization

You need to install the {maia} app in the GitHub organization account that hosts the repository. To do this, follow the steps in [Installing the {maia} app in GitHub](/docs/guides/installing-matillion-app-github-marketplace).

You should install the app in your *organization* GitHub account, not a *personal* GitHub account. You may need to confirm with the GitHub account admin/owner that you can install the {maia} GitHub app and create a repository.

To confirm that the {maia} app has been installed in the correct organization, visit `https://github.com/organizations/<your-org-name>/settings/installations` (replace `<your-org-name>` with the org name in your GitHub URL).

***

## 3 - Set up GitHub repository roles

The user connecting a GitHub repository to a {maia} project will need at least the `Write` GitHub repository role to actively work on data pipelines in {designer} via the GitHub repository.

When you create an internal repository, all members of your GitHub org will have a base role that can be either Read, Triage, Write, Maintain, or Admin. If the base role is not Write, make sure to add users to your repository that have the Write role.

If you created a private repository, you will need to add members of your GitHub org to your repository and grant them the `Write` role.

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.

***

## 4 - Set up project access in Designer (optional)

If you wish to collaborate with other {maia} users on the same project, add them to your project by following the instructions at [Project roles](/docs/administration/project-roles). Make sure these users are members of the same GitHub organization where the {maia} app is installed and where you created the repository that you connected to your project.

***

## Related pages

* [Installing the {maia} app in the GitHub Marketplace](/docs/guides/installing-matillion-app-github-marketplace)
* [Troubleshooting GitHub repository connection](/docs/guides/troubleshooting-github-repository-connection)