Skip to main content
First create and install a GitHub App. GitHub sign-in is separate and uses OAuth settings.

​
Add the instance credentials

For the bundled Compose deployment, add these values to .env:
Encode the downloaded PEM file without printing it into logs or committing it. Alternatively, set GITHUB_PRIVATE_KEY to the full PEM with real line breaks or literal \n sequences. GITHUB_PRIVATE_KEY_BASE64 takes precedence if both are present. Recreate the application container to apply the environment:
For Kubernetes, pass the same values through a Secret using your deployment’s existing secret configuration. Do not create a second API deployment just for this integration.

​
Connect the project

  1. Open Settings → Projects, select the project, then open Integrations and select Connect next to GitHub.
  2. Link your GitHub account if Kaneo asks for it. Kaneo uses it to confirm that you administer the repository.
  3. Type the repository as owner/name, or select Browse and search the repositories your installed app can reach. Kaneo checks the installation as soon as you pick one.
  4. Select Connect repository.
  5. Create a test task and check that its GitHub issue appears.
Use a test repository for the first check, since synchronization creates real issues and comments. Review the event-to-column mappings under Workflow → Automations.

​
Changing the connected repository

Disconnect the existing integration before connecting a different repository. This preserves local tasks but removes their old external links and any unfinished import progress. Reconnecting the same verified repository, including after a rename or reinstall, preserves its links and project preferences. Legacy integrations without a verified numeric identity can be reverified for the same repository name; review their existing links before enabling synchronization.

​
Testing the Integration

After connecting a repository, test the integration thoroughly:
1
Test Task to Issue CreationCreate 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
2
Test Automatic Status TransitionsTest 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”
Default branch pattern is {slug}-{number}. You can customize this in project settings.
3
Test Issue to Task SyncIn 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
4
Test Label SynchronizationTest 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

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

​
Pull Request Task References

Kaneo checks the configured branch pattern first, then explicit task references in the PR title and body. Use your project key, such as PROJ-42 or fix(PROJ-42): correct the link, or an explicit task: 42 marker. Task markers require a separator after task; words such as task42 do not identify a task. Issue references use the remote repository’s numbering. A title containing #61 or a body containing Closes #61 resolves through the issue link recorded by this integration. If GitHub issue 61 is linked to Kaneo task PROJ-42, the PR belongs to PROJ-42, even if PROJ-61 also exists. Same-repository owner/repo#61 references and issue URLs are also supported. References to another repository are ignored. Links from Copy task link, such as https://kaneo.example.com/acme/task/PROJ-42/fix-login, contain the project key, so pasting one in the PR title or body links the PR to that task. If none of those match, Kaneo also looks for a full task URL (/dashboard/workspace/.../task/...). A PR with full URLs to more than one task, or to a task in another project, is not linked. Without an explicit task reference, unmapped issues do not create PR associations. References that map to multiple tasks within the integration are skipped. Repeated issue links to the same task are accepted. Bare numeric title shortcuts such as [42], (42), or 42: ... are not task identifiers; use the project key instead. GitHub webhooks also skip conflicting candidates or an existing PR association across projects connected to the repository. Signed Gitea webhooks resolve only within their authenticated integration; another project’s mappings or PR links do not block that integration. Direct Gitea handler calls without an integration ID use the repository-wide checks. Imports for both providers remain scoped to the selected project. These rules apply to new associations from webhooks and imports. Existing PR associations within the applicable scope are preserved; historical incorrect links require separate correction.

​
Status Transition Configuration

Customize when tasks automatically change status: Configure these under Workflow → Automations to match your workflow.
A completed task moves again only when new work starts on it: the first push to a branch that is not yet linked to the task, or a pull request that is not yet linked to it. More pushes to a linked branch, or reopening a pull request, leave a completed task where it is.

​
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 for common problems and solutions.

​
Import existing issues

Select Import issues in the project’s GitHub integration settings to import open issues and their labels and comments. Existing linked tasks are updated; matching open pull requests are linked to their tasks. Bot comments are excluded. Large imports run in small, sequential steps. Keep the page open until the completion message appears. If the connection fails or you close the page, the saved progress remains available: return to these settings and select Resume import. The completion message lists created, updated and skipped issues. A skipped issue may have lost its source or linked task during the import, or have a legacy link to another project. Each run uses its start time as a cutoff for newly created issues, pull requests and comments. Label and comment counts are bounded by the first page observed for each issue, so additions during an import may require a new import after the current run completes. GitHub can change during a run; this is not an exact point-in-time snapshot. Reimporting does not duplicate already linked tasks or comments. If GitHub is unavailable or rate limits requests, wait before resuming. Reconnect the integration if its repository verification no longer succeeds. Unlinking the integration also removes saved import progress; already imported tasks remain.