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

# App Setup

> Learn how to create and configure a GitHub App for Kaneo integration. Step-by-step guide to register your Kaneo instance with GitHub.

This guide walks you through creating and configuring a GitHub App to enable the Kaneo integration. **Start here before deploying or configuring your Kaneo instance.**

## Overview

A GitHub App provides secure, granular access to your repositories and enables powerful bidirectional synchronization between Kaneo and GitHub:

**Task to GitHub:**

* Automatically create GitHub issues when you create tasks
* Update issue status and priority labels when you change tasks
* Add comments linking to Kaneo tasks
* Close/reopen issues based on task status changes

**GitHub to Kaneo:**

* Create tasks from GitHub issues
* Sync issue labels (priority, status) to task properties
* Link pull requests to tasks automatically
* Update task status based on branch activity (push, PR open/merge)
* Sync GitHub labels to Kaneo task labels

**Automatic Status Transitions:**

* Branch push → Move task to "in-progress"
* PR opened → Move task to "in-review"
* PR merged → Move task to "done"

<Info>
  GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.
</Info>

<Warning>
  **Important**: Complete this GitHub App setup **before** deploying Kaneo. You'll need the app credentials during deployment configuration.
</Warning>

## Step 1: Create a GitHub App

<Steps>
  <Step>
    **Navigate to GitHub App Settings**

    Go to [GitHub Developer Settings](https://github.com/settings/developers) and click "New GitHub App".
  </Step>

  <Step>
    **Configure Basic Information**

    Fill in the basic app information:

    * **GitHub App name**: `kaneo-[your-instance-name]` (must be unique across GitHub)
    * **Description**: `Kaneo project management integration`
    * **Homepage URL**: Your planned Kaneo instance URL (e.g., `https://kaneo.yourdomain.com`)
    * **Webhook URL**: `https://your-kaneo-instance.com/api/github-integration/webhook`
    * **Webhook secret**: Generate a secure random string (save this for later)

    <Warning>
      Replace `your-kaneo-instance.com` with your planned Kaneo domain. The webhook URL must be publicly accessible once deployed.
    </Warning>
  </Step>

  <Step>
    **Set Repository Permissions**

    Configure the following permissions:

    | Permission        | Access       | Purpose                                                                |
    | ----------------- | ------------ | ---------------------------------------------------------------------- |
    | **Issues**        | Read & Write | Create issues, add/remove labels, create comments, close/reopen issues |
    | **Pull Requests** | Read         | Link pull requests to tasks and track PR status                        |
    | **Metadata**      | Read         | Access repository information and verify installation                  |
    | **Contents**      | Read         | Track branch pushes and associate commits with tasks                   |

    <Warning>
      **Critical**: Make sure to grant **Write** access to Issues - this is required for the integration to work properly.
    </Warning>

    <Info>
      Pull Requests permission is optional but recommended for full integration features. Without it, you won't be able to automatically link PRs to tasks or track PR status changes.
    </Info>
  </Step>

  <Step>
    **Subscribe to Webhook Events**

    **This step is required for proper integration.** Subscribe to these events:

    * **Issues** - To sync issues with tasks (opened, edited, closed, labeled, unlabeled)
    * **Issue comments** - To track comments on linked issues
    * **Pull requests** - To link PRs to tasks and update task status (opened, closed, reopened, merged)
    * **Push** - To automatically update task status based on branch activity

    <Warning>
      **Required**: You must subscribe to **Issues** events for bidirectional synchronization to work.
    </Warning>

    <Info>
      **Recommended**: Subscribe to all four event types for full integration features:

      * **Issues**: Creates tasks from issues and syncs status/labels
      * **Issue comments**: Tracks GitHub discussions
      * **Pull requests**: Auto-updates task status when PRs are opened/merged
      * **Push**: Moves tasks to "in-progress" when branches are pushed
    </Info>

    <Warning>
      Without **Push** and **Pull requests** events, automatic status transitions won't work (e.g., moving tasks to "in-progress" on branch push or "done" on PR merge).
    </Warning>
  </Step>

  <Step>
    **Create the App**

    Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.
  </Step>
</Steps>

## Step 2: Generate Credentials

<Steps>
  <Step>
    **Generate and Download Private Key**

    1. Scroll down to the "Private keys" section
    2. Click "Generate a private key"
    3. Download the `.pem` file - you'll need its contents for configuration

    <Warning>
      Keep this private key secure! It's used to authenticate your Kaneo instance with GitHub.
    </Warning>
  </Step>

  <Step>
    **Note Your App Information**

    From the app settings page, note down these important values:

    * **App ID** (shown at the top of the page)
    * **Webhook Secret** (the one you created earlier)
    * **Private Key** (contents of the downloaded `.pem` file)

    The GitHub App also shows an OAuth **Client ID** and **Client Secret** under "Basic information". Kaneo’s **repository integration** does not use those environment variables; they are only relevant if you enable **Sign in with GitHub** using `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (see [GitHub SSO](/core/social-providers/github)).

    <Info>
      You need **App ID**, **private key**, and **webhook secret** for the [configuration step](/core/integrations/github/configuration).
    </Info>
  </Step>
</Steps>

## Step 3: Install the App

<Steps>
  <Step>
    **Install on Your Account/Organization**

    1. Go to your GitHub App settings page
    2. Click "Install App" in the left sidebar
    3. Choose your account or organization
    4. Select repositories:
       * **All repositories** (if you want integration available for all repos)
       * **Selected repositories** (choose specific repos)

    <Tip>
      You can modify repository access later by going to your [GitHub App installations](https://github.com/settings/installations).
    </Tip>
  </Step>

  <Step>
    **Verify Installation**

    After installation, you should see your app listed in:

    * [Your GitHub App installations](https://github.com/settings/installations)
    * The repository's Settings → Integrations & services (for organization repos)
  </Step>
</Steps>

## Security Best Practices

### App Configuration

* **Use descriptive names**: Make it clear the app is for Kaneo integration
* **Limit permissions**: Only grant the minimum required permissions
* **Repository scope**: Install only on repositories that need integration

### Credential Management

* **Secure storage**: Store credentials in environment variables or secret management systems
* **Regular rotation**: Generate new private keys periodically
* **Access control**: Limit who has access to the GitHub App settings

## Common Issues

### App Name Already Taken

If your desired app name is taken, try:

* Adding your organization name: `kaneo-mycompany`
* Adding a timestamp: `kaneo-mycompany-2024`
* Using a different naming convention: `mycompany-kaneo`

### Webhook URL Not Accessible

Ensure your Kaneo instance is:

* Publicly accessible on the internet
* Using HTTPS (GitHub requires this for webhooks)
* Not behind authentication that would block GitHub's webhook calls

### Permission Issues

Double-check that you've granted:

* **Write** access to Issues (not just Read)
* **Read** access to Pull Requests (for PR linking)
* **Read** access to Metadata and Contents
* Selected the correct repositories during installation

### Webhook Events Not Working

If automatic synchronization isn't happening:

* Verify all webhook events are subscribed (Issues, Issue comments, Pull requests, Push)
* Check webhook deliveries in GitHub App settings for failed deliveries
* Ensure your webhook URL is publicly accessible and using HTTPS

## Next Steps

Now that your GitHub App is created and configured:

1. **[Deploy Kaneo](/core)** - Deploy your Kaneo instance with the GitHub App credentials
2. **[Configure GitHub Integration](/core/integrations/github/configuration)** - Complete the integration setup in your deployed Kaneo instance
3. **[Connect Repositories](/core/integrations/github/configuration#connecting-repositories)** - Link your projects to GitHub repositories

<Info>
  **Important**: Have your GitHub App credentials ready before deployment. You'll need to set them as environment variables during the deployment process.
</Info>

***

**Need help?** Check our [troubleshooting guide](/core/integrations/github/troubleshooting) or ask for help on [Discord](https://discord.gg/rU4tSyhXXU).