Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

3.1 KB
Raw Blame
---
title: Set up the GitHub integration
description: Sync GitHub issues, comments, and pull requests with Kaneo projects by creating a GitHub App for your self-hosted instance.
---

A self-hosted Kaneo instance uses a GitHub App for repository sync. Create the app once, install it on the repositories you need, then [connect each Kaneo project](/core/integrations/github/configuration).

GitHub sign-in is a separate feature. Use the [GitHub sign-in guide](/core/social-providers/github) for that setup.

## 1. Register the app

Open [GitHub Developer Settings](https://github.com/settings/apps) and choose **New GitHub App**.

| Setting | Value |
| --- | --- |
| App name | A unique name, such as `kaneo-your-team` |
| Homepage URL | Your public Kaneo URL |
| Webhook URL | `https://kaneo.example.com/api/github-integration/webhook` |
| Webhook secret | A random secret you will also configure in Kaneo |

Keep webhooks active. GitHub must be able to reach the endpoint without signing in to your reverse proxy. Use your actual public API origin if you host it separately.

## 2. Set permissions and events

Use these repository permissions:

| Permission | Access | Used for |
| --- | --- | --- |
| Issues | Read and write | Issue creation, edits, comments, labels, and open/closed state |
| Pull requests | Read | Pull-request links and status changes |
| Contents | Read | Branch and push activity |
| Metadata | Read | Repository discovery and installation checks |

Subscribe to **Issues**, **Issue comments**, **Pull requests**, and **Push**. If you later change the app’s permissions, approve the updated permissions on its installation too.

Create the app. GitHub’s [app registration guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) explains the remaining platform settings.

## 3. Save the credentials

On the app’s settings page, record its **App ID** and app slug. Generate and download a private key from **Private keys**. Keep the webhook secret you chose earlier.

Kaneo’s repository integration needs the App ID, private key, and webhook secret. It does not use the app’s OAuth Client ID or Client Secret for repository access.

## 4. Install on your repositories

Choose **Install App**, select your GitHub account or organization, and select the repositories to connect. You can change that selection later under [GitHub App installations](https://github.com/settings/installations).

An organization may require an owner to approve the installation or permission changes. Finish that approval before verifying access in Kaneo.

## 5. Connect Kaneo

Follow [Connect a GitHub repository](/core/integrations/github/configuration) to add the instance credentials, connect a project, and import issues.

Tasks and issues can sync in both directions. Branch and pull-request activity can move tasks according to your [workflow mappings](/core/functional/configure-workflows); check those mappings against your project’s actual columns.

If verification or sync fails, check [GitHub troubleshooting](/core/integrations/github/troubleshooting).