App Setup
Learn how to create and configure a GitHub App for Kaneo integration. Step-by-step guide to register your Kaneo instance with GitHub.
This guide walks you through creating and configuring a GitHub App to enable the Kaneo integration. Start here before deploying or configuring your Kaneo instance.
Overview
A GitHub App provides secure, granular access to your repositories and enables powerful bidirectional synchronization between Kaneo and GitHub:
Task to GitHub:
- Automatically create GitHub issues when you create tasks
- Update issue status and priority labels when you change tasks
- Add comments linking to Kaneo tasks
- Close/reopen issues based on task status changes
GitHub to Kaneo:
- Create tasks from GitHub issues
- Sync issue labels (priority, status) to task properties
- Link pull requests to tasks automatically
- Update task status based on branch activity (push, PR open/merge)
- Sync GitHub labels to Kaneo task labels
Automatic Status Transitions:
- Branch push → Move task to "in-progress"
- PR opened → Move task to "in-review"
- PR merged → Move task to "done"
GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.
Important: Complete this GitHub App setup before deploying Kaneo. You'll need the app credentials during deployment configuration.
Step 1: Create a GitHub App
Navigate to GitHub App Settings
Go to GitHub Developer Settings and click "New GitHub App".
Configure Basic Information
Fill in the basic app information:
- GitHub App name:
kaneo-[your-instance-name](must be unique across GitHub) - Description:
Kaneo project management integration - Homepage URL: Your planned Kaneo instance URL (e.g.,
https://kaneo.yourdomain.com) - Webhook URL:
https://your-kaneo-instance.com/api/github-integration/webhook - Webhook secret: Generate a secure random string (save this for later)
Replace your-kaneo-instance.com with your planned Kaneo domain. The webhook URL must be publicly accessible once deployed.
Set Repository Permissions
Configure the following permissions:
| Permission | Access | Purpose |
|---|---|---|
| Issues | Read & Write | Create issues, add/remove labels, create comments, close/reopen issues |
| Pull Requests | Read | Link pull requests to tasks and track PR status |
| Metadata | Read | Access repository information and verify installation |
| Contents | Read | Track branch pushes and associate commits with tasks |
Critical: Make sure to grant Write access to Issues - this is required for the integration to work properly.
Pull 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.
Subscribe to Webhook Events
This step is required for proper integration. Subscribe to these events:
- Issues - To sync issues with tasks (opened, edited, closed, labeled, unlabeled)
- Issue comments - To track comments on linked issues
- Pull requests - To link PRs to tasks and update task status (opened, closed, reopened, merged)
- Push - To automatically update task status based on branch activity
Required: You must subscribe to Issues events for bidirectional synchronization to work.
Recommended: Subscribe to all four event types for full integration features:
- Issues: Creates tasks from issues and syncs status/labels
- Issue comments: Tracks GitHub discussions
- Pull requests: Auto-updates task status when PRs are opened/merged
- Push: Moves tasks to "in-progress" when branches are pushed
Without 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).
Create the App
Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.
Step 2: Generate Credentials
Generate and Download Private Key
- Scroll down to the "Private keys" section
- Click "Generate a private key"
- Download the
.pemfile - you'll need its contents for configuration
Keep this private key secure! It's used to authenticate your Kaneo instance with GitHub.
Note Your App Information
From the app settings page, note down these important values:
- App ID (shown at the top of the page)
- Client ID (in the "Basic information" section)
- Client Secret (click "Generate a new client secret")
- Webhook Secret (the one you created earlier)
- Private Key (contents of the downloaded
.pemfile)
You'll need all of these values for the configuration step.
Step 3: Install the App
Install on Your Account/Organization
- Go to your GitHub App settings page
- Click "Install App" in the left sidebar
- Choose your account or organization
- Select repositories:
- All repositories (if you want integration available for all repos)
- Selected repositories (choose specific repos)
You can modify repository access later by going to your GitHub App installations.
Verify Installation
After installation, you should see your app listed in:
- Your GitHub App installations
- The repository's Settings → Integrations & services (for organization repos)
Security Best Practices
App Configuration
- Use descriptive names: Make it clear the app is for Kaneo integration
- Limit permissions: Only grant the minimum required permissions
- Repository scope: Install only on repositories that need integration
Credential Management
- Secure storage: Store credentials in environment variables or secret management systems
- Regular rotation: Generate new private keys periodically
- Access control: Limit who has access to the GitHub App settings
Common Issues
App Name Already Taken
If your desired app name is taken, try:
- Adding your organization name:
kaneo-mycompany - Adding a timestamp:
kaneo-mycompany-2024 - Using a different naming convention:
mycompany-kaneo
Webhook URL Not Accessible
Ensure your Kaneo instance is:
- Publicly accessible on the internet
- Using HTTPS (GitHub requires this for webhooks)
- Not behind authentication that would block GitHub's webhook calls
Permission Issues
Double-check that you've granted:
- Write access to Issues (not just Read)
- Read access to Pull Requests (for PR linking)
- Read access to Metadata and Contents
- Selected the correct repositories during installation
Webhook Events Not Working
If automatic synchronization isn't happening:
- Verify all webhook events are subscribed (Issues, Issue comments, Pull requests, Push)
- Check webhook deliveries in GitHub App settings for failed deliveries
- Ensure your webhook URL is publicly accessible and using HTTPS
Next Steps
Now that your GitHub App is created and configured:
- Deploy Kaneo - Deploy your Kaneo instance with the GitHub App credentials
- Configure GitHub Integration - Complete the integration setup in your deployed Kaneo instance
- Connect Repositories - Link your projects to GitHub repositories
Important: Have your GitHub App credentials ready before deployment. You'll need to set them as environment variables during the deployment process.
Need help? Check our troubleshooting guide or ask for help on Discord.