---
title: Configuration & Setup
description: 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.

<Info>
Make sure you've completed the [GitHub App setup](/core/integrations/github/setup) before proceeding.
</Info>

## Environment Variables

Add the following environment variables to your Kaneo deployment:

```bash
# 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` |

<Warning>
`GITHUB_APP_NAME` is optional but recommended. It's used to generate direct installation links in the UI.
</Warning>

## Deployment Examples

### Docker Compose

Update your `compose.yml` file:

```yaml
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
```

<Tip>
Use the `|` YAML syntax for multi-line environment variables like the private key.
</Tip>

### Kubernetes

Create a secret for your GitHub credentials:

```yaml
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:

```yaml
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:

```bash
# .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.

<Steps>
<Step>
**Navigate to Project Settings**

1. Open your Kaneo project
2. Go to **Project Settings**
3. Find the **GitHub Integration** section
</Step>

<Step>
**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"
</Step>

<Step>
**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

<Check>
Once connected, new tasks created in this project will automatically generate GitHub issues!
</Check>
</Step>
</Steps>

## Testing the Integration

After connecting a repository, test the integration thoroughly:

<Steps>
<Step>
**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
</Step>

<Step>
**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"

<Info>
Default branch pattern is `{slug}-{number}`. You can customize this in project settings.
</Info>
</Step>

<Step>
**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
</Step>

<Step>
**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
</Step>

</Steps>

## 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.

<Tip>
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.
</Tip>

### 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.

<Warning>
Status transitions only apply if the task is not already in "done" status. This prevents accidentally reopening completed tasks.
</Warning>

### 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](/core/integrations/github/troubleshooting) for common problems and solutions.