Configuration & Setup

Configure Kaneo with your GitHub App credentials and connect projects to repositories. Includes Docker Compose and Kubernetes examples.

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 (integration only — repository sync, webhooks)
GITHUB_APP_ID=123456
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 slug for installation URLs in the UI
GITHUB_APP_NAME=kaneo-your-instance-name

GitHub sign-in uses separate OAuth variables (GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET). You can run the integration without enabling GitHub SSO. See GitHub SSO and Environment variables.

Variable Reference

Variable	Description	Required	Example
GITHUB_APP_ID	Your GitHub App’s ID	✅	123456
GITHUB_PRIVATE_KEY	Full private key content (with newlines)	✅	-----BEGIN RSA...
GITHUB_WEBHOOK_SECRET	Secret for webhook verification	✅	your-secret
GITHUB_APP_NAME	App slug for installation URLs in the UI	⚠️	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_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_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_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.

1. Navigate to Project Settings

   1. Open your Kaneo project
   2. Go to Project Settings
   3. Find the GitHub Integration section
2. Connect Repository

   You have two options to connect a repository:

   Option A: Browse Repositories

   1. Click “Browse Repositories”
   2. Select from repositories where your GitHub App is installed
   3. Click on the desired repository

   Option B: Manual Entry

   1. Enter the Repository Owner (username or organization)
   2. Enter the Repository Name
   3. Click “Verify Installation”
3. Verify and Connect

   1. Kaneo will verify that your GitHub App has access
   2. If successful, click “Connect Repository”
   3. 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 thoroughly:

1. Test Task to Issue Creation

   Create a new task in your connected Kaneo project with:

   • A clear title
   • A description
   • Set priority and status

   Navigate to your GitHub repository and verify:

   • A new issue was created
   • The issue has priority:* and status:* labels
   • A comment links back to the Kaneo task
2. Test Automatic Status Transitions

   Test branch-based workflow:

   1. Note your task number (e.g., PROJ-123)
   2. Create and push a branch matching the pattern (e.g., proj-123)
   3. Verify the task moves to “in-progress”
   4. Open a PR from that branch
   5. Verify the task moves to “in-review”
   6. Merge the PR
   7. Verify the task moves to “done”

   Default branch pattern is {slug}-{number}. You can customize this in project settings.

3. Test Issue to Task Sync

   In GitHub:

   1. Create a new issue
   2. Add labels like priority:high or status:in-progress

   In Kaneo:

   • Verify a task was created from the issue
   • Check that priority and status match the labels
   • Confirm the task links to the GitHub issue
4. Test Label Synchronization

   Test both directions:

   1. Change task priority in Kaneo → Check issue labels in GitHub
   2. Add/remove labels in GitHub → Check task in Kaneo
   3. Change task status in Kaneo → Check if issue is closed/reopened

Advanced Configuration

Branch Naming Patterns

Configure how Kaneo matches branches to tasks in your project’s GitHub integration settings:

Predefined Patterns:

• {slug}-{number} (default) - e.g., proj-123
• {slug}-{number}-{title} - e.g., proj-123-fix-bug
• {number} - e.g., 123
• {number}-{title} - e.g., 123-fix-bug
• feature/{slug}-{number} - e.g., feature/proj-123
• fix/{slug}-{number} - e.g., fix/proj-123

Custom Regex: You can also provide a custom regex pattern for more complex matching.

The {slug} variable is your project’s slug (case-insensitive), {number} is the task number, and {title} is an optional slug of the task title.

Status Transition Configuration

Customize when tasks automatically change status:

Event	Default Status	Customizable
Branch Push	in-progress	✅
PR Opened	in-review	✅
PR Merged	done	✅

Configure these in your project’s GitHub integration settings to match your workflow.

Status transitions only apply if the task is not already in “done” status. This prevents accidentally reopening completed tasks.

Label Synchronization

Kaneo automatically creates and syncs these label types:

System Labels (managed automatically):

• priority:low, priority:medium, priority:high, priority:urgent
• status:to-do, status:in-progress, status:in-review, status:done, status:planned, status:archived

Custom Labels:

• Any labels added to GitHub issues (not starting with priority: or status:) are synced to Kaneo
• Labels added in Kaneo can be synced to GitHub (if configured)

Multiple Organizations

If you need to connect repositories from multiple GitHub organizations:

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

---

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