danieldaum.net
kaneo (minimalist kanban) fork to experiment adding a tangled integration
github.com/usekaneo/kaneo
1---
2title: App Setup
3description: Learn how to create and configure a GitHub App for Kaneo integration. Step-by-step guide to register your Kaneo instance with GitHub.
4---
5
6
7This guide walks you through creating and configuring a GitHub App to enable the Kaneo integration. **Start here before deploying or configuring your Kaneo instance.**
8
9## Overview
10
11A GitHub App provides secure, granular access to your repositories and enables powerful bidirectional synchronization between Kaneo and GitHub:
12
13**Task to GitHub:**
14- Automatically create GitHub issues when you create tasks
15- Update issue status and priority labels when you change tasks
16- Add comments linking to Kaneo tasks
17- Close/reopen issues based on task status changes
18
19**GitHub to Kaneo:**
20- Create tasks from GitHub issues
21- Sync issue labels (priority, status) to task properties
22- Link pull requests to tasks automatically
23- Update task status based on branch activity (push, PR open/merge)
24- Sync GitHub labels to Kaneo task labels
25
26**Automatic Status Transitions:**
27- Branch push → Move task to "in-progress"
28- PR opened → Move task to "in-review"
29- PR merged → Move task to "done"
30
31<Info>
32GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.
33</Info>
34
35<Warning>
36**Important**: Complete this GitHub App setup **before** deploying Kaneo. You'll need the app credentials during deployment configuration.
37</Warning>
38
39## Step 1: Create a GitHub App
40
41<Steps>
42<Step>
43**Navigate to GitHub App Settings**
44
45Go to [GitHub Developer Settings](https://github.com/settings/developers) and click "New GitHub App".
46</Step>
47
48<Step>
49**Configure Basic Information**
50
51Fill in the basic app information:
52
53- **GitHub App name**: `kaneo-[your-instance-name]` (must be unique across GitHub)
54- **Description**: `Kaneo project management integration`
55- **Homepage URL**: Your planned Kaneo instance URL (e.g., `https://kaneo.yourdomain.com`)
56- **Webhook URL**: `https://your-kaneo-instance.com/api/github-integration/webhook`
57- **Webhook secret**: Generate a secure random string (save this for later)
58
59<Warning>
60Replace `your-kaneo-instance.com` with your planned Kaneo domain. The webhook URL must be publicly accessible once deployed.
61</Warning>
62</Step>
63
64<Step>
65**Set Repository Permissions**
66
67Configure the following permissions:
68
69| Permission | Access | Purpose |
70|------------|---------|---------|
71| **Issues** | Read & Write | Create issues, add/remove labels, create comments, close/reopen issues |
72| **Pull Requests** | Read | Link pull requests to tasks and track PR status |
73| **Metadata** | Read | Access repository information and verify installation |
74| **Contents** | Read | Track branch pushes and associate commits with tasks |
75
76<Warning>
77**Critical**: Make sure to grant **Write** access to Issues - this is required for the integration to work properly.
78</Warning>
79
80<Info>
81Pull Requests permission is optional but recommended for full integration features. Without it, you won't be able to automatically link PRs to tasks or track PR status changes.
82</Info>
83</Step>
84
85<Step>
86**Subscribe to Webhook Events**
87
88**This step is required for proper integration.** Subscribe to these events:
89
90- **Issues** - To sync issues with tasks (opened, edited, closed, labeled, unlabeled)
91- **Issue comments** - To track comments on linked issues
92- **Pull requests** - To link PRs to tasks and update task status (opened, closed, reopened, merged)
93- **Push** - To automatically update task status based on branch activity
94
95<Warning>
96**Required**: You must subscribe to **Issues** events for bidirectional synchronization to work.
97</Warning>
98
99<Info>
100**Recommended**: Subscribe to all four event types for full integration features:
101- **Issues**: Creates tasks from issues and syncs status/labels
102- **Issue comments**: Tracks GitHub discussions
103- **Pull requests**: Auto-updates task status when PRs are opened/merged
104- **Push**: Moves tasks to "in-progress" when branches are pushed
105</Info>
106
107<Warning>
108Without **Push** and **Pull requests** events, automatic status transitions won't work (e.g., moving tasks to "in-progress" on branch push or "done" on PR merge).
109</Warning>
110</Step>
111
112<Step>
113**Create the App**
114
115Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.
116</Step>
117</Steps>
118
119## Step 2: Generate Credentials
120
121<Steps>
122<Step>
123**Generate and Download Private Key**
124
1251. Scroll down to the "Private keys" section
1262. Click "Generate a private key"
1273. Download the `.pem` file - you'll need its contents for configuration
128
129<Warning>
130Keep this private key secure! It's used to authenticate your Kaneo instance with GitHub.
131</Warning>
132</Step>
133
134<Step>
135**Note Your App Information**
136
137From the app settings page, note down these important values:
138
139- **App ID** (shown at the top of the page)
140- **Client ID** (in the "Basic information" section)
141- **Client Secret** (click "Generate a new client secret")
142- **Webhook Secret** (the one you created earlier)
143- **Private Key** (contents of the downloaded `.pem` file)
144
145<Info>
146You'll need all of these values for the [configuration step](/core/integrations/github/configuration).
147</Info>
148</Step>
149</Steps>
150
151## Step 3: Install the App
152
153<Steps>
154<Step>
155**Install on Your Account/Organization**
156
1571. Go to your GitHub App settings page
1582. Click "Install App" in the left sidebar
1593. Choose your account or organization
1604. Select repositories:
161 - **All repositories** (if you want integration available for all repos)
162 - **Selected repositories** (choose specific repos)
163
164<Tip>
165You can modify repository access later by going to your [GitHub App installations](https://github.com/settings/installations).
166</Tip>
167</Step>
168
169<Step>
170**Verify Installation**
171
172After installation, you should see your app listed in:
173- [Your GitHub App installations](https://github.com/settings/installations)
174- The repository's Settings → Integrations & services (for organization repos)
175</Step>
176</Steps>
177
178## Security Best Practices
179
180### App Configuration
181- **Use descriptive names**: Make it clear the app is for Kaneo integration
182- **Limit permissions**: Only grant the minimum required permissions
183- **Repository scope**: Install only on repositories that need integration
184
185### Credential Management
186- **Secure storage**: Store credentials in environment variables or secret management systems
187- **Regular rotation**: Generate new private keys periodically
188- **Access control**: Limit who has access to the GitHub App settings
189
190## Common Issues
191
192### App Name Already Taken
193If your desired app name is taken, try:
194- Adding your organization name: `kaneo-mycompany`
195- Adding a timestamp: `kaneo-mycompany-2024`
196- Using a different naming convention: `mycompany-kaneo`
197
198### Webhook URL Not Accessible
199Ensure your Kaneo instance is:
200- Publicly accessible on the internet
201- Using HTTPS (GitHub requires this for webhooks)
202- Not behind authentication that would block GitHub's webhook calls
203
204### Permission Issues
205Double-check that you've granted:
206- **Write** access to Issues (not just Read)
207- **Read** access to Pull Requests (for PR linking)
208- **Read** access to Metadata and Contents
209- Selected the correct repositories during installation
210
211### Webhook Events Not Working
212If automatic synchronization isn't happening:
213- Verify all webhook events are subscribed (Issues, Issue comments, Pull requests, Push)
214- Check webhook deliveries in GitHub App settings for failed deliveries
215- Ensure your webhook URL is publicly accessible and using HTTPS
216
217## Next Steps
218
219Now that your GitHub App is created and configured:
220
2211. **[Deploy Kaneo](/core)** - Deploy your Kaneo instance with the GitHub App credentials
2222. **[Configure GitHub Integration](/core/integrations/github/configuration)** - Complete the integration setup in your deployed Kaneo instance
2233. **[Connect Repositories](/core/integrations/github/configuration#connecting-repositories)** - Link your projects to GitHub repositories
224
225<Info>
226**Important**: Have your GitHub App credentials ready before deployment. You'll need to set them as environment variables during the deployment process.
227</Info>
228
229---
230
231**Need help?** Check our [troubleshooting guide](/core/integrations/github/troubleshooting) or ask for help on [Discord](https://discord.gg/rU4tSyhXXU).