danieldaum.net
kaneo (minimalist kanban) fork to experiment adding a tangled integration
github.com/usekaneo/kaneo
1---
2title: Configuration & Setup
3description: Configure Kaneo with your GitHub App credentials and connect projects to repositories. Includes Docker Compose and Kubernetes examples.
4---
5
6
7This guide covers configuring Kaneo with your GitHub App credentials and connecting projects to repositories.
8
9<Info>
10Make sure you've completed the [GitHub App setup](/core/integrations/github/setup) before proceeding.
11</Info>
12
13## Environment Variables
14
15Add the following environment variables to your Kaneo deployment:
16
17```bash
18# GitHub App Configuration
19GITHUB_APP_ID=123456
20GITHUB_CLIENT_ID=Iv1.abc123def456
21GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu
22GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
23MIIEpAIBAAKCAQEA...
24[Full contents of your private key]
25...
26-----END RSA PRIVATE KEY-----"
27GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
28
29# Optional: GitHub App Name for installation URLs
30GITHUB_APP_NAME=kaneo-your-instance-name
31```
32
33### Variable Reference
34
35| Variable | Description | Required | Example |
36|----------|-------------|----------|---------|
37| `GITHUB_APP_ID` | Your GitHub App's ID | ✅ | `123456` |
38| `GITHUB_CLIENT_ID` | OAuth client ID from your app | ✅ | `Iv1.abc123def456` |
39| `GITHUB_CLIENT_SECRET` | OAuth client secret | ✅ | `abc123def456ghi789jkl012mno345pqr678stu` |
40| `GITHUB_PRIVATE_KEY` | Full private key content (with newlines) | ✅ | `-----BEGIN RSA...` |
41| `GITHUB_WEBHOOK_SECRET` | Secret for webhook verification | ✅ | `your-secret` |
42| `GITHUB_APP_NAME` | App name for installation URLs | ⚠️ | `kaneo-mycompany` |
43
44<Warning>
45`GITHUB_APP_NAME` is optional but recommended. It's used to generate direct installation links in the UI.
46</Warning>
47
48## Deployment Examples
49
50### Docker Compose
51
52Update your `compose.yml` file:
53
54```yaml
55services:
56 backend:
57 image: ghcr.io/usekaneo/api:latest
58 environment:
59 # ... other environment variables
60 GITHUB_APP_ID: "123456"
61 GITHUB_CLIENT_ID: "Iv1.abc123def456"
62 GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"
63 GITHUB_PRIVATE_KEY: |
64 -----BEGIN RSA PRIVATE KEY-----
65 MIIEpAIBAAKCAQEA...
66 [Full contents of your private key]
67 ...
68 -----END RSA PRIVATE KEY-----
69 GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"
70 GITHUB_APP_NAME: "kaneo-mycompany"
71 # ... rest of configuration
72```
73
74<Tip>
75Use the `|` YAML syntax for multi-line environment variables like the private key.
76</Tip>
77
78### Kubernetes
79
80Create a secret for your GitHub credentials:
81
82```yaml
83apiVersion: v1
84kind: Secret
85metadata:
86 name: github-integration
87 namespace: kaneo
88type: Opaque
89stringData:
90 GITHUB_APP_ID: "123456"
91 GITHUB_CLIENT_ID: "Iv1.abc123def456"
92 GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"
93 GITHUB_PRIVATE_KEY: |
94 -----BEGIN RSA PRIVATE KEY-----
95 MIIEpAIBAAKCAQEA...
96 [Full contents of your private key]
97 ...
98 -----END RSA PRIVATE KEY-----
99 GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"
100 GITHUB_APP_NAME: "kaneo-mycompany"
101```
102
103Then reference it in your deployment:
104
105```yaml
106apiVersion: apps/v1
107kind: Deployment
108metadata:
109 name: kaneo-backend
110spec:
111 template:
112 spec:
113 containers:
114 - name: backend
115 image: ghcr.io/usekaneo/api:latest
116 envFrom:
117 - secretRef:
118 name: github-integration
119```
120
121### Environment File
122
123For development or simple deployments, create a `.env` file:
124
125```bash
126# .env file
127GITHUB_APP_ID=123456
128GITHUB_CLIENT_ID=Iv1.abc123def456
129GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu
130GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
131MIIEpAIBAAKCAQEA...
132[Full contents of your private key]
133...
134-----END RSA PRIVATE KEY-----"
135GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
136GITHUB_APP_NAME=kaneo-mycompany
137```
138
139## Connecting Repositories
140
141Once your environment variables are configured and your backend is restarted, you can connect projects to GitHub repositories.
142
143<Steps>
144<Step>
145**Navigate to Project Settings**
146
1471. Open your Kaneo project
1482. Go to **Project Settings**
1493. Find the **GitHub Integration** section
150</Step>
151
152<Step>
153**Connect Repository**
154
155You have two options to connect a repository:
156
157**Option A: Browse Repositories**
1581. Click "Browse Repositories"
1592. Select from repositories where your GitHub App is installed
1603. Click on the desired repository
161
162**Option B: Manual Entry**
1631. Enter the **Repository Owner** (username or organization)
1642. Enter the **Repository Name**
1653. Click "Verify Installation"
166</Step>
167
168<Step>
169**Verify and Connect**
170
1711. Kaneo will verify that your GitHub App has access
1722. If successful, click "Connect Repository"
1733. You should see a green "Connected" status
174
175<Check>
176Once connected, new tasks created in this project will automatically generate GitHub issues!
177</Check>
178</Step>
179</Steps>
180
181## Testing the Integration
182
183After connecting a repository, test the integration thoroughly:
184
185<Steps>
186<Step>
187**Test Task to Issue Creation**
188
189Create a new task in your connected Kaneo project with:
190- A clear title
191- A description
192- Set priority and status
193
194Navigate to your GitHub repository and verify:
195- A new issue was created
196- The issue has `priority:*` and `status:*` labels
197- A comment links back to the Kaneo task
198</Step>
199
200<Step>
201**Test Automatic Status Transitions**
202
203Test branch-based workflow:
2041. Note your task number (e.g., `PROJ-123`)
2052. Create and push a branch matching the pattern (e.g., `proj-123`)
2063. Verify the task moves to "in-progress"
2074. Open a PR from that branch
2085. Verify the task moves to "in-review"
2096. Merge the PR
2107. Verify the task moves to "done"
211
212<Info>
213Default branch pattern is `{slug}-{number}`. You can customize this in project settings.
214</Info>
215</Step>
216
217<Step>
218**Test Issue to Task Sync**
219
220In GitHub:
2211. Create a new issue
2222. Add labels like `priority:high` or `status:in-progress`
223
224In Kaneo:
225- Verify a task was created from the issue
226- Check that priority and status match the labels
227- Confirm the task links to the GitHub issue
228</Step>
229
230<Step>
231**Test Label Synchronization**
232
233Test both directions:
2341. Change task priority in Kaneo → Check issue labels in GitHub
2352. Add/remove labels in GitHub → Check task in Kaneo
2363. Change task status in Kaneo → Check if issue is closed/reopened
237</Step>
238
239</Steps>
240
241## Advanced Configuration
242
243### Branch Naming Patterns
244
245Configure how Kaneo matches branches to tasks in your project's GitHub integration settings:
246
247**Predefined Patterns:**
248- `{slug}-{number}` (default) - e.g., `proj-123`
249- `{slug}-{number}-{title}` - e.g., `proj-123-fix-bug`
250- `{number}` - e.g., `123`
251- `{number}-{title}` - e.g., `123-fix-bug`
252- `feature/{slug}-{number}` - e.g., `feature/proj-123`
253- `fix/{slug}-{number}` - e.g., `fix/proj-123`
254
255**Custom Regex:**
256You can also provide a custom regex pattern for more complex matching.
257
258<Tip>
259The `{slug}` variable is your project's slug (case-insensitive), `{number}` is the task number, and `{title}` is an optional slug of the task title.
260</Tip>
261
262### Status Transition Configuration
263
264Customize when tasks automatically change status:
265
266| Event | Default Status | Customizable |
267|-------|---------------|--------------|
268| Branch Push | `in-progress` | ✅ |
269| PR Opened | `in-review` | ✅ |
270| PR Merged | `done` | ✅ |
271
272Configure these in your project's GitHub integration settings to match your workflow.
273
274<Warning>
275Status transitions only apply if the task is not already in "done" status. This prevents accidentally reopening completed tasks.
276</Warning>
277
278### Label Synchronization
279
280Kaneo automatically creates and syncs these label types:
281
282**System Labels** (managed automatically):
283- `priority:low`, `priority:medium`, `priority:high`, `priority:urgent`
284- `status:to-do`, `status:in-progress`, `status:in-review`, `status:done`, `status:planned`, `status:archived`
285
286**Custom Labels:**
287- Any labels added to GitHub issues (not starting with `priority:` or `status:`) are synced to Kaneo
288- Labels added in Kaneo can be synced to GitHub (if configured)
289
290### Multiple Organizations
291If you need to connect repositories from multiple GitHub organizations:
292
2931. Install your GitHub App on each organization
2942. Grant appropriate permissions for each organization
2953. Each Kaneo project can connect to any repository where your app is installed
296
297---
298
299**Having issues?** Check our [troubleshooting guide](/core/integrations/github/troubleshooting) for common problems and solutions.