App Setup

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 allows Kaneo to:

Create issues automatically when tasks are created
Access repository metadata for verification
Receive webhook events for issue synchronization

GitHub Apps are more secure than personal access tokens and provide better permission control.

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

Step 1: Create a GitHub App

Navigate to GitHub App Settings

Go to GitHub Developer Settings and click "New GitHub App".

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/github-integration/webhook
Webhook secret: Generate a secure random string (save this for later)

Replace your-kaneo-instance.com with your planned Kaneo domain. The webhook URL must be publicly accessible once deployed.

Set Repository Permissions

Configure the following permissions:

Permission	Access	Purpose
Issues	Read & Write	Create and update issues
Metadata	Read	Access repository information
Contents	Read	Access repository metadata

Critical: Make sure to grant Write access to Issues - this is required for creating issues automatically.

Subscribe to Webhook Events

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

Issues - To track when issues are created, updated, or closed
Issue Comments - To track comments on issues

Required: You must subscribe to Issues events for the integration to work properly. This enables bidirectional synchronization between Kaneo tasks and GitHub issues.

These webhook events enable real-time synchronization between your Kaneo tasks and GitHub issues.

Create the App

Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.

Step 2: Generate Credentials

Generate and Download Private Key

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

Keep this private key secure! It's used to authenticate your Kaneo instance with GitHub.

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)

You'll need all of these values for the configuration step.

Step 3: Install the App

Install on Your Account/Organization

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

You can modify repository access later by going to your GitHub App installations.

Verify Installation

After installation, you should see your app listed in:

Your GitHub App installations
The repository's Settings → Integrations & services (for organization repos)

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 Metadata and Contents
Selected the correct repositories during installation

Next Steps

Now that your GitHub App is created and configured:

Deploy Kaneo - Deploy your Kaneo instance with the GitHub App credentials
Configure GitHub Integration - Complete the integration setup in your deployed Kaneo instance
Connect Repositories - Link your projects to GitHub repositories

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

Need help? Check our troubleshooting guide or ask for help on Discord.

On this page