Installing the Maia app in GitHub

Read Prerequisites for connecting a GitHub repository to Maia before installing the app.

---

How to install the app

1. Log in to GitHub.
2. Navigate to the Maia Integration app page.
3. Make sure you are about to install the app in your company’s organization account and not your personal GitHub account, and then click Install.
4. Select All repositories or Only select repositories.
   • If you select All repositories, you can choose any current or new repos in your GitHub organization when you create a new project in Maia.
   • If you select Only select repositories, choose the repository that you created for the sole purpose of developing your Designer pipelines.

Once the Maia app is installed in your organization’s GitHub account, you can create your project in Designer and connect your project to the GitHub repository.

---

One-time installation

You only need to install the Maia app in your GitHub organization account once. After this, whenever you create a new project in Maia, you can connect to any repositories that you grant Maia access to. If you wish to revoke or change Designer‘s access to your repositories, go to https://github.com/organizations/<your-org-name>/settings/installations (change <your-org-name> to the organization in your GitHub URL) and click Configure.

---

Required GitHub App permissions

When installing or using the Maia app for GitHub, the following repository permissions are required:

• Read and write access to contents: Repository contents, commits, branches, downloads, releases, and merges.
• Read and write access to Workflows: GitHub Actions workflow files under .github/workflows/.

These permissions enable Maia to commit changes, manage branches, and update GitHub Actions workflows in your repository.

---

Organizations that use an IP allowlist

If your GitHub organization restricts access with an IP allowlist, GitHub blocks Maia unless the Maia IP addresses are on the list. IP allowlists are a GitHub Enterprise Cloud feature. You can allow Maia in either of the following ways.

Add the IP addresses for your region

Add the Maia IP addresses for Git repositories for the region where your Maia account is hosted to your organization’s allowlist. This allows only the IP addresses that your account uses.

Let GitHub add the Maia app’s IP addresses

The Maia app has its own IP allowlist. An organization owner can turn on a GitHub setting that adds the allowlists of all installed GitHub Apps to your organization’s allowlist:

1. In GitHub, navigate to your organization’s Settings.
2. In the settings menu, under Security, click Authentication security.
3. In the IP allow list section, select Enable IP allow list configuration for installed GitHub Apps.
4. Click Save.

GitHub then adds the Maia app’s IP addresses to your allowlist and keeps them up to date if they change. GitHub labels these entries “Managed by the Maia for GitHub GitHub App”, and you can’t edit or delete them. They only allow requests that the Maia app makes, not other traffic from those IP addresses. Allow a few minutes for changes to take effect. Before you turn on this setting, note that:

• The Maia app’s allowlist includes the IP addresses for every Maia region, not only the region where your account is hosted. To allow only your region’s IP addresses, add them yourself instead.
• The setting adds the IP addresses of every GitHub App installed in your organization, not only the Maia app.

If your enterprise account manages the IP allowlist for all of its organizations, an enterprise owner turns on the same setting in the enterprise’s authentication security settings instead. For more information, read Allowing access by GitHub Apps in the GitHub documentation.