---
title: App Setup
description: 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)
- **Client ID** (in the "Basic information" section)
- **Client Secret** (click "Generate a new client secret")
- **Webhook Secret** (the one you created earlier)
- **Private Key** (contents of the downloaded `.pem` file)

<Info>
You'll need all of these values 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).