Kaneo LogoKaneo
Integrations/GitHub

Troubleshooting

This guide helps you diagnose and fix common issues with the GitHub integration.

Common Issues

"GitHub App not installed" Error

Problem: Verification shows the app isn't installed on the repository.

Symptoms:

  • Red error message in Kaneo UI
  • "Connect Repository" button remains disabled
  • Repository doesn't appear in the browser modal

Solutions:

  1. Check Installation Scope

    • Go to GitHub App installations
    • Verify your app is installed on the correct account/organization
    • Check if the target repository is included in the installation scope

  2. Reinstall with Broader Access

    • Edit your app installation
    • Change from "Selected repositories" to "All repositories"
    • Or add the specific repository to the selected list

  3. Verify Repository Ownership

    • Ensure you're entering the correct repository owner (username/organization)
    • Check that the repository name is spelled correctly
    • Verify the repository exists and you have access to it

Use the "Browse Repositories" feature in Kaneo to see which repositories your app can access.

"Missing Permissions" Error

Problem: App is installed but lacks required permissions.

Symptoms:

  • Orange warning in verification
  • App appears in installations but can't create issues
  • Missing permissions listed in the error message

Solutions:

  1. Update App Permissions

    • Go to your GitHub App settings
    • Edit your app and check permissions:
      • Issues: Must have Write access (not just Read)
      • Metadata: Must have Read access
      • Contents: Must have Read access

  2. Update Installation

    • After changing app permissions, you may need to update the installation
    • Go to GitHub App installations
    • Click "Configure" next to your app
    • Review and accept any permission changes

  3. Check Organization Permissions

    • For organization repositories, ensure the organization allows the app
    • Organization owners may need to approve third-party apps

"Repository not found" Error

Problem: Repository exists but isn't accessible to the app.

Symptoms:

  • Repository not found in verification
  • 404-style errors in logs
  • Repository doesn't appear in browse modal

Solutions:

  1. Verify Repository Details

    • Double-check the repository owner and name
    • Ensure there are no typos or extra spaces
    • Check that the repository is public or your app has access to private repos

  2. Check Private Repository Access

    • Private repositories require explicit app installation
    • Ensure your GitHub App is installed on the repository owner's account
    • Verify the app has permission to access private repositories

  3. Organization Repository Issues

    • Check if the organization has third-party app restrictions
    • Ensure the app is approved by organization owners
    • Verify the app is installed at the organization level, not just personal account

Environment Variable Issues

Problem: Integration doesn't work after configuration.

Symptoms:

  • No GitHub issues created when tasks are made
  • Authentication errors in logs
  • Integration appears configured but doesn't function

Solutions:

  1. Verify All Variables Are Set

    # Check if environment variables are loaded
echo $GITHUB_APP_ID
echo $GITHUB_CLIENT_ID
# etc.

  2. Check Private Key Format

    • Ensure GITHUB_PRIVATE_KEY includes the full content with proper line breaks
    • The key should start with -----BEGIN RSA PRIVATE KEY-----
    • The key should end with -----END RSA PRIVATE KEY-----
    • Include all newlines and formatting from the .pem file

  3. Restart Backend Service

    • Environment variable changes require a service restart
    • For Docker Compose: docker compose restart backend
    • For Kubernetes: kubectl rollout restart deployment/kaneo-backend

  4. Check Log Output

    • Look for authentication errors on startup
    • Verify the GitHub App ID is recognized
    • Check for private key parsing errors

Make sure your private key doesn't have any extra characters or missing newlines.

Webhook Issues

Webhook Not Receiving Events

Problem: GitHub events aren't reaching Kaneo.

Symptoms:

  • Webhook events listed in GitHub but no logs in Kaneo
  • Webhook delivery failures in GitHub App settings

Solutions:

  1. Verify Webhook URL

    • Ensure the URL is publicly accessible: https://your-domain.com/github-integration/webhook
    • Test accessibility from external tools like curl or online checkers
    • Verify your domain has proper DNS resolution

  2. Check HTTPS Configuration

    • GitHub requires HTTPS for webhook endpoints
    • Ensure your SSL certificate is valid and not self-signed
    • Test your webhook endpoint with online SSL checkers

  3. Firewall and Network Issues

    • Ensure GitHub's IP ranges can reach your server
    • Check if your hosting provider blocks incoming webhooks
    • Verify no authentication middleware is blocking the webhook endpoint

Webhook Signature Verification Fails

Problem: Webhooks reach Kaneo but signature verification fails.

Symptoms:

  • "Invalid signature" errors in logs
  • Webhook events rejected with 400 status

Solutions:

  1. Verify Webhook Secret

    • Ensure GITHUB_WEBHOOK_SECRET matches exactly what you set in the GitHub App
    • Check for extra spaces or characters
    • The secret is case-sensitive

  2. Check Secret Configuration

    • In GitHub App settings, verify the webhook secret is set
    • If you changed the secret, update the environment variable and restart
    • Generate a new secret if there are persistent issues

Testing and Debugging

Testing the Integration

Follow these steps to systematically test your integration:

  1. Verify Environment Variables

    # Check that all required variables are set (don't print private key!)
echo "App ID: $GITHUB_APP_ID"
echo "Client ID: $GITHUB_CLIENT_ID"
echo "Webhook Secret: [REDACTED]"
echo "App Name: $GITHUB_APP_NAME"

  2. Test Repository Access

    • Use the "Browse Repositories" feature in Kaneo
    • Verify your target repository appears in the list
    • Try connecting a test repository first

  3. Create a Test Task

    • Create a simple task in your connected project
    • Check GitHub immediately for the new issue
    • Verify the issue format and labels are correct

  4. Check Backend Logs Look for these log messages:

    ✅ GitHub issue created: { issueNumber: 42, issueUrl: "...", taskId: "...", repository: "..." }
❌ Failed to create GitHub issue: [error details]
✅ Task created: { taskId: "...", title: "...", projectId: "..." }

Log Analysis

Successful Integration Logs:

Task created: { taskId: "task_123", title: "Fix bug", projectId: "proj_456" }
Creating GitHub issue for repository: owner/repo
GitHub issue created: { issueNumber: 42, issueUrl: "https://github.com/owner/repo/issues/42" }

Common Error Patterns:

❌ No active GitHub integration found for project: proj_456
❌ Failed to create GitHub issue: HttpError: Bad credentials
❌ Repository not found: owner/nonexistent-repo
❌ App installation not found for repository: owner/repo

GitHub App Diagnostics

Use GitHub's built-in tools to diagnose issues:

  1. App Installation Page

  2. Webhook Delivery Logs

    • In your GitHub App settings, check the "Advanced" tab
    • Review recent webhook deliveries and their status codes
    • Look for failed deliveries or error responses

  3. Repository Integration Status

    • Go to your repository's Settings → Integrations & services
    • Verify your app appears in the list
    • Check the app's permissions and access

Getting Help

If you're still experiencing issues:

Before Asking for Help

  1. Check Your Setup

    • Verify all environment variables are correct
    • Ensure your GitHub App has the right permissions
    • Test with a simple repository first

  2. Gather Information

    • Note the exact error messages
    • Check both Kaneo logs and GitHub webhook delivery logs
    • Document your environment (Docker, Kubernetes, etc.)

  3. Test Basic Functionality

    • Try creating a task without GitHub integration
    • Verify your Kaneo instance is working normally
    • Test with different repositories if possible

Support Channels

What to Include in Support Requests

  1. Environment Details

    • Kaneo version
    • Deployment method (Docker, Kubernetes, etc.)
    • Operating system

  2. Error Information

    • Exact error messages
    • Screenshots of the issue
    • Relevant log entries

  3. Configuration Details

    • Which environment variables you've set (don't share secret values!)
    • GitHub App permissions you've granted
    • Repository details (without sharing sensitive info)

When sharing logs or error messages, always redact sensitive information like private keys, secrets, or access tokens.

Still stuck? The Kaneo community is here to help! Join our Discord for real-time support.

Edit on GitHub

Configuration & Setup

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

Core Concepts

Understanding the key concepts in Kaneo

On this page