---
title: GitHub Integration
description: Learn how to connect your GitHub repositories to Capawesome Cloud to build and automate your app directly from source.
---

# GitHub Integration

Connect your GitHub repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io){:target="_blank"} account and an organization (owner or admin role to manage Git connections).
- A GitHub account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git){:target="_blank"} page and click **Create Git connection**.
2. Select **GitHub** as the provider.
3. Choose one of the authentication methods below and follow the corresponding steps.

!!! warning "Already using GitHub via OAuth?"

    Support for GitHub connections with the personal account (OAuth) method ended on **November 1, 2026**. All remaining OAuth connections are removed on **December 31, 2026**. Follow the steps in [Upgrade from personal account (OAuth)](#upgrade-from-personal-account-oauth) to switch to the GitHub App.

### GitHub App (recommended)

The GitHub App is the recommended method. Repository access is managed on GitHub, and no tokens are stored in Capawesome Cloud. Each connection is tied to a single GitHub user or organization account — to use repositories from multiple accounts, create a separate connection for each.

1. Select **GitHub App** as the authentication method.
2. Click **Continue to GitHub**.
3. Install and configure the Capawesome Cloud GitHub App on your GitHub user or organization account, and select which repositories it can access.
4. After confirming on GitHub, you are returned to the console and the connection is created.

To change which repositories the app can access later, use **Configure on GitHub** — repository access is always managed on GitHub.

!!! tip "Least privilege"

    Select only the repositories Capawesome Cloud needs to build your app instead of granting access to all repositories.

### Personal access token (PAT)

Paste a token you create on GitHub. This works for GitHub.com and, via the **Server URL** field, GitHub Enterprise Server.

1. Create a GitHub personal access token. GitHub offers two token types:
    - **Fine-grained token** (recommended): grant **Contents: Read-only** (**Metadata: Read-only** is added automatically). To enable [Automations](../automations/index.md), also grant **Webhooks: Read and write**.
    - **Classic token**: grant the `repo` scope — it already includes webhook management. For public repositories only, `public_repo` is enough (add `admin:repo_hook` for automations).
2. Select **Personal access token (PAT)** as the authentication method and paste the token.
3. For **GitHub Enterprise Server** (self-hosted), enable **Self-hosted or enterprise instance** and enter your server's **Server URL**.

!!! tip "Least privilege"

    Prefer a fine-grained token: restrict it to the repositories needed for the build and grant only the permissions listed above. Classic tokens cannot be limited to single repositories.

!!! note "Organization repositories"

    For a repository owned by an organization, a classic token may need to be authorized for SSO, and a fine-grained token may require approval by an organization owner.

## Upgrade from personal account (OAuth)

Connections with the personal account (OAuth) method use the GitHub account you signed in with, which had to grant access to all of its repositories. Support for this method ended on November 1, 2026. Signing in no longer requests access to your repositories. All remaining OAuth connections are removed on December 31, 2026.

An organization owner or admin can upgrade such a connection to the GitHub App in place. The connection keeps its ID, so all apps linked to it, their builds and their automations keep working without any further changes.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git){:target="_blank"} page.
2. Open the actions menu of the connection with the authentication method **Personal account (OAuth)** and click **Edit**.
3. Select **GitHub App** as the authentication method and click **Continue to GitHub**.
4. Install the Capawesome Cloud GitHub App on the GitHub user or organization account that owns the repositories, and select the repositories your apps use.
5. After confirming on GitHub, you are returned to the console. The connection now shows **GitHub App** as its authentication method.

Keep the following in mind:

- **One account per connection**: A GitHub App installation covers a single GitHub user or organization account. If the connection is used for repositories of several accounts, first create a separate GitHub App connection for each additional account and connect the affected apps to it: open the app's **Git repository** page, click **Disconnect**, then **Connect Git repository** and select the new connection. Then upgrade the original connection for the remaining account.
- **Approval by a GitHub organization owner**: If you are not an owner of the GitHub organization, GitHub only records an installation request. The connection is marked as **Pending** and does not work until an organization owner approves the request on GitHub. To avoid this, let a GitHub organization owner run the upgrade.
- **Alternative**: If you cannot install the GitHub App, edit the connection and switch to a [personal access token](#personal-access-token-pat) instead.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git){:target="_blank"} page and click **Connect Git repository**.
2. Select the GitHub connection.
3. Select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).

## Troubleshooting

### Organization repository not visible

If an organization's repositories do not appear when selecting a repository, the connection may not have access to them. Configure repository access for the Capawesome Cloud GitHub App on GitHub, or check that a personal access token is authorized for the organization.