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

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

    Existing GitHub connections created with the personal account (OAuth) method keep working. You can upgrade them to the GitHub App at any time from the connection's edit dialog. Read the [Git integration revamp announcement](../../blog/posts/git-integration-revamp-in-capawesome-cloud.md) to learn why we recommend the switch.

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

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

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

## 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 re-authorize the personal account so it can see the organization's repositories.