Configuration & Setup

This guide covers configuring Kaneo with your GitHub App credentials and connecting projects to repositories.

Make sure you've completed the GitHub App setup before proceeding.

Environment Variables

Add the following environment variables to your Kaneo deployment:

# GitHub App Configuration
GITHUB_APP_ID=123456
GITHUB_CLIENT_ID=Iv1.abc123def456
GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
[Full contents of your private key]
...
-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
 
# Optional: GitHub App Name for installation URLs
GITHUB_APP_NAME=kaneo-your-instance-name

Variable Reference

Variable	Description	Required	Example
`GITHUB_APP_ID`	Your GitHub App's ID	✅	`123456`
`GITHUB_CLIENT_ID`	OAuth client ID from your app	✅	`Iv1.abc123def456`
`GITHUB_CLIENT_SECRET`	OAuth client secret	✅	`abc123def456ghi789jkl012mno345pqr678stu`
`GITHUB_PRIVATE_KEY`	Full private key content (with newlines)	✅	`-----BEGIN RSA...`
`GITHUB_WEBHOOK_SECRET`	Secret for webhook verification	✅	`your-secret`
`GITHUB_APP_NAME`	App name for installation URLs	⚠️	`kaneo-mycompany`

GITHUB_APP_NAME is optional but recommended. It's used to generate direct installation links in the UI.

Deployment Examples

Docker Compose

Update your compose.yml file:

services:
  backend:
    image: ghcr.io/usekaneo/api:latest
    environment:
      # ... other environment variables
      GITHUB_APP_ID: "123456"
      GITHUB_CLIENT_ID: "Iv1.abc123def456"
      GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"
      GITHUB_PRIVATE_KEY: |
        -----BEGIN RSA PRIVATE KEY-----
        MIIEpAIBAAKCAQEA...
        [Full contents of your private key]
        ...
        -----END RSA PRIVATE KEY-----
      GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"
      GITHUB_APP_NAME: "kaneo-mycompany"
    # ... rest of configuration

Use the | YAML syntax for multi-line environment variables like the private key.

Kubernetes

Create a secret for your GitHub credentials:

apiVersion: v1
kind: Secret
metadata:
  name: github-integration
  namespace: kaneo
type: Opaque
stringData:
  GITHUB_APP_ID: "123456"
  GITHUB_CLIENT_ID: "Iv1.abc123def456"
  GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"
  GITHUB_PRIVATE_KEY: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEA...
    [Full contents of your private key]
    ...
    -----END RSA PRIVATE KEY-----
  GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"
  GITHUB_APP_NAME: "kaneo-mycompany"

Then reference it in your deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kaneo-backend
spec:
  template:
    spec:
      containers:
      - name: backend
        image: ghcr.io/usekaneo/api:latest
        envFrom:
        - secretRef:
            name: github-integration

Environment File

For development or simple deployments, create a .env file:

# .env file
GITHUB_APP_ID=123456
GITHUB_CLIENT_ID=Iv1.abc123def456
GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
[Full contents of your private key]
...
-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
GITHUB_APP_NAME=kaneo-mycompany

Connecting Repositories

Once your environment variables are configured and your backend is restarted, you can connect projects to GitHub repositories.

Navigate to Project Settings

Open your Kaneo project
Go to Project Settings
Find the GitHub Integration section

Connect Repository

You have two options to connect a repository:

Option A: Browse Repositories

Click "Browse Repositories"
Select from repositories where your GitHub App is installed
Click on the desired repository

Option B: Manual Entry

Enter the Repository Owner (username or organization)
Enter the Repository Name
Click "Verify Installation"

Verify and Connect

Kaneo will verify that your GitHub App has access
If successful, click "Connect Repository"
You should see a green "Connected" status

Once connected, new tasks created in this project will automatically generate GitHub issues!

Testing the Integration

After connecting a repository, test the integration:

Create a Test Task

Create a new task in your connected Kaneo project with:

A clear title
A description
Set priority and status

Check GitHub

Navigate to your connected GitHub repository and check if:

A new issue was created
The issue title starts with [Kaneo]
The issue has appropriate labels (kaneo, priority:*, status:*)
The issue body contains task details

Advanced Configuration

Multiple Organizations

If you need to connect repositories from multiple GitHub organizations:

Install your GitHub App on each organization
Grant appropriate permissions for each organization
Each Kaneo project can connect to any repository where your app is installed

Custom Labels

Currently, Kaneo uses these default labels:

kaneo - All issues created by Kaneo
priority:high|medium|low - Based on task priority
status:todo|in-progress|done - Based on task status

Future versions will support custom label configurations.

Having issues? Check our troubleshooting guide for common problems and solutions.

Configuration & Setup

On this page