Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

9.2 KB
Raw Blame
---
title: "Connect a GitHub repository"
description: "Add the app credentials, connect a project, and verify synchronization."
---

First [create and install a GitHub App](/core/integrations/github/setup). GitHub sign-in is separate and uses [OAuth settings](/core/social-providers/github).

## Add the instance credentials

For the bundled Compose deployment, add these values to `.env`:

```env
GITHUB_APP_ID=your-app-id
GITHUB_APP_NAME=your-app-slug
GITHUB_WEBHOOK_SECRET=your-webhook-secret
GITHUB_PRIVATE_KEY_BASE64=your-base64-encoded-private-key
```

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:

```bash
docker compose up -d --force-recreate kaneo
```

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:

<Steps>
<Step>
**Test Task to Issue Creation**

Create 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
</Step>

<Step>
**Test Automatic Status Transitions**

Test 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"

<Info>
Default branch pattern is `{slug}-{number}`. You can customize this in project settings.
</Info>
</Step>

<Step>
**Test Issue to Task Sync**

In 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
</Step>

<Step>
**Test Label Synchronization**

Test 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
</Step>

</Steps>

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

<Tip>
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.
</Tip>

### 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:

| Event | Default Status | Customizable |
|-------|---------------|--------------|
| Branch Push | `in-progress` | ✅ |
| PR Opened | `in-review` | ✅ |
| PR Merged | `done` | ✅ |

Configure these under **Workflow → Automations** to match your workflow.

<Warning>
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.
</Warning>

### 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](/core/integrations/github/troubleshooting) 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.