|
1 | 1 | --- |
2 | | -title: Import from GitHub |
3 | | -description: Bring GitHub issues into Kagan as tasks in a few steps |
| 2 | +title: GitHub integration |
| 3 | +description: Two-way metadata sync, create-and-link, and `#`-mention autocomplete for GitHub Issues |
4 | 4 | icon: material/github |
5 | 5 | tags: |
6 | 6 | - github |
7 | | - - import |
| 7 | + - integration |
8 | 8 | --- |
9 | 9 |
|
10 | | -# Import from GitHub |
| 10 | +# GitHub integration |
11 | 11 |
|
12 | | -Kagan has built-in GitHub issue import. Bring existing issues onto your board in a few steps. |
| 12 | +Kagan integrates with GitHub Issues at three points: |
| 13 | + |
| 14 | +1. **Import** issues from a repository as Kagan tasks. |
| 15 | +2. **Create-and-link** — when creating a Kagan task, optionally link it to an existing issue or create a fresh issue from the task. |
| 16 | +3. **`#`-mention autocomplete** — type `#` anywhere in a Kagan text field to insert a link to a Kagan task or a GitHub issue. |
| 17 | + |
| 18 | +The integration uses the GitHub CLI (`gh`) for auth — no token plumbing. |
13 | 19 |
|
14 | 20 | ## What you need |
15 | 21 |
|
16 | 22 | - GitHub CLI installed: <https://cli.github.com> |
17 | | -- Signed in on your machine: `gh auth login` |
18 | | -- A Kagan project already created |
| 23 | +- Signed in: `gh auth login` |
| 24 | +- A Kagan project linked to a Git repo whose `origin` points at GitHub |
19 | 25 |
|
20 | | -## Import in the TUI |
| 26 | +## How sync works |
21 | 27 |
|
22 | | -GitHub import uses a two-step flow: |
| 28 | +Once a task is linked to a GitHub issue, Kagan keeps the following fields in sync **bidirectionally** on every pull/push: |
23 | 29 |
|
24 | | -**Step 1 — Filter:** |
| 30 | +| Field | Direction | |
| 31 | +| ------------------------- | -------------------------------------------- | |
| 32 | +| Title | both ways | |
| 33 | +| Body / description | both ways, **verbatim** — no scaffolding | |
| 34 | +| Priority labels | both ways (`priority:critical/high/medium/low`) | |
| 35 | +| Acceptance criteria | both ways via a tagged comment (see below) | |
25 | 36 |
|
26 | | -1. Open your project board in `kagan` |
27 | | -1. Open Actions with `.` |
28 | | -1. Run `github import` |
29 | | -1. Enter your repository in `owner/repo` format |
30 | | -1. Choose issue state (`open`, `closed`, or `all`) |
31 | | -1. Optionally enter comma-separated labels to filter by (e.g. `bug, feature`) |
32 | | -1. Optionally set a limit (default 100) |
33 | | -1. Press `Enter` to preview matching issues |
| 37 | +What does **not** sync: |
34 | 38 |
|
35 | | -**Step 2 — Select:** |
| 39 | +- **Status / lifecycle.** Moving a Kagan task to `DONE` does not close the GitHub issue. Closing an issue on GitHub does not move the Kagan task. They are independent concepts — a Kanban column is not the same as an issue lifecycle state. |
| 40 | +- **Comments** other than the Kagan-managed acceptance-criteria comment. |
| 41 | +- **Assignees, milestones, projects** — not in scope for this integration. |
36 | 42 |
|
37 | | -1. Review the list of matching issues — already-synced ones are shown with `(synced)` and deselected by default |
38 | | -1. Use `Space` to toggle individual issues, `a` to select all, `n` to deselect all |
39 | | -1. Press `Enter` to import selected issues, or `Esc` to go back and adjust filters |
| 43 | +The body is stored exactly as it appears on GitHub. Kagan does not prepend the URL, inject `[label]` tags, or add any other scaffolding to the description. Round-trips are stable. |
40 | 44 |
|
41 | | -Kagan shows a summary with created, skipped, and error counts. |
| 45 | +## Acceptance criteria |
42 | 46 |
|
43 | | -## Preview before import |
| 47 | +GitHub already has a checklist convention (`- [ ]` / `- [x]`). Kagan uses it in two ways: |
44 | 48 |
|
45 | | -See what issues match your filters before committing to the import: |
| 49 | +1. **First import** — checklist lines in the issue body seed the Kagan task's acceptance criteria. The body is left untouched. |
| 50 | +2. **Subsequent edits** — when criteria change in Kagan, Kagan upserts a single comment on the issue tagged with `<!-- kagan:acceptance-criteria -->`. The comment body is a clean checklist. On every pull, if that comment exists Kagan re-derives criteria from it; otherwise it falls back to the body seed. |
46 | 51 |
|
47 | | -```bash |
48 | | -kagan plugins preview github --repo octocat/hello-world |
49 | | -``` |
| 52 | +The issue body is never modified by criteria sync — only the tagged comment is. |
50 | 53 |
|
51 | | -Optional flags: |
| 54 | +## Create and link |
52 | 55 |
|
53 | | -- `--state open|closed|all` |
54 | | -- `--label <label>` (repeatable) — filter by one or more labels |
55 | | -- `--limit <n>` — cap the number of issues returned (default 100) |
| 56 | +When creating a Kagan task on any surface (TUI, web, VS Code, MCP, chat), the `github_issue` field accepts: |
| 57 | + |
| 58 | +- empty / `none` → no link. |
| 59 | +- `42` / `#42` → link to the existing issue in the project's linked repo. |
| 60 | +- `owner/repo#42` → link to an issue in a specific repo. |
| 61 | +- `new` → create a new GitHub issue from the task's title and description, then link. |
56 | 62 |
|
57 | | -Output shows issue number, title, state, labels, and whether the issue is already synced. |
| 63 | +The link is stored on the task as `<owner>/<repo>#<number>` and is what every later sync operation keys on. |
58 | 64 |
|
59 | | -## Import from CLI |
| 65 | +## Import |
| 66 | + |
| 67 | +### CLI |
60 | 68 |
|
61 | 69 | ```bash |
62 | | -kagan plugins sync github --repo octocat/hello-world |
| 70 | +kagan import github --repo owner/repo |
63 | 71 | ``` |
64 | 72 |
|
65 | 73 | Optional flags: |
66 | 74 |
|
67 | 75 | - `--state open|closed|all` |
68 | | -- `--label <label>` (repeatable) — filter by one or more labels |
69 | | -- `--limit <n>` — max issues to fetch (default 100) |
70 | | -- `--issues 1,2,42` — import only specific issue numbers |
| 76 | +- `--label <label>` (repeatable) |
| 77 | +- `--limit <n>` (default 100) |
| 78 | +- `--issues 1,2,42` — import specific numbers only |
71 | 79 |
|
72 | | -Examples: |
| 80 | +### TUI |
73 | 81 |
|
74 | | -```bash |
75 | | -# Import only bug issues |
76 | | -kagan plugins sync github --repo octocat/hello-world --label bug |
| 82 | +Press `.` for Actions → run `github import` → enter repo (auto-detected from `origin`), state, optional labels → preview list with toggles → import. |
77 | 83 |
|
78 | | -# Import multiple label filters |
79 | | -kagan plugins sync github --repo octocat/hello-world --label bug --label priority:high |
| 84 | +### Web |
80 | 85 |
|
81 | | -# Import specific issues by number |
82 | | -kagan plugins sync github --repo octocat/hello-world --issues 12,34,56 |
83 | | -``` |
| 86 | +Click **Import from GitHub** on the board toolbar. Same fields, same preview, same toggles. |
| 87 | + |
| 88 | +### VS Code |
| 89 | + |
| 90 | +Command palette → **Kagan: Import from GitHub**. Same flow. |
| 91 | + |
| 92 | +### MCP |
| 93 | + |
| 94 | +`github_preview` and `github_sync` tools mirror the HTTP routes 1:1. Useful for orchestrator agents and external MCP clients. |
| 95 | + |
| 96 | +### Chat |
| 97 | + |
| 98 | +Ask the orchestrator: *"import open issues from owner/repo"*. The orchestrator calls `github_sync` via MCP. |
| 99 | + |
| 100 | +## `#`-mention autocomplete |
| 101 | + |
| 102 | +Type `#` in any Kagan text field — task description, acceptance criterion, chat message, code editor (VS Code) — and a typeahead opens listing matches from two sources: |
| 103 | + |
| 104 | +- **Kagan tasks** in the current project (matched by short id and title). |
| 105 | +- **GitHub issues** in the linked repo (matched by number and title). |
| 106 | + |
| 107 | +Pick a Kagan task → inserts `kagan#<short_id>`. Pick a GitHub issue → inserts `#<number>`. Both forms are clickable in rendered markdown: |
| 108 | + |
| 109 | +- `kagan#abc12345` → opens the task in-app. |
| 110 | +- `#42` → opens the issue on GitHub. |
| 111 | + |
| 112 | +If the project has no linked GitHub repo, the typeahead still works — Kagan-only. |
| 113 | + |
| 114 | +## Cross-client parity |
| 115 | + |
| 116 | +Every capability above is reachable from every client: |
| 117 | + |
| 118 | +| Capability | CLI | TUI | Web | VS Code | Chat | MCP | |
| 119 | +| ---------------- | --- | --- | --- | ------- | ---- | --- | |
| 120 | +| Import | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
| 121 | +| Create-and-link | — | ✓ | ✓ | ✓ | ✓ | ✓ | |
| 122 | +| `#`-mention | — | ✓ | ✓ | ✓ | ✓ | ✓ | |
| 123 | + |
| 124 | +(CLI does not have a generic `task create` command today — task creation is via the TUI or any of the API-driven clients.) |
84 | 125 |
|
85 | 126 | ## Label mapping |
86 | 127 |
|
87 | | -These labels map automatically when importing: |
| 128 | +These labels auto-map to Kagan priorities on import and on push-back: |
88 | 129 |
|
89 | 130 | - `priority:critical`, `priority:high`, `priority:medium`, `priority:low` |
90 | 131 |
|
91 | | -Other labels are kept in the task description as tags. |
| 132 | +If the label doesn't exist on the repo when Kagan first sets it, Kagan creates it (`gh label create`) with a sensible default colour. |
92 | 133 |
|
93 | 134 | ## Troubleshooting |
94 | 135 |
|
95 | | -- `GitHub CLI (gh) not found` -> install from <https://cli.github.com> |
96 | | -- `GitHub CLI not authenticated` -> run `gh auth login` |
97 | | -- `repo must be in owner/repo format` -> use `owner/repo`, for example `octocat/hello-world` |
| 136 | +- `GitHub CLI (gh) not found` → install from <https://cli.github.com>. |
| 137 | +- `GitHub CLI not authenticated` → `gh auth login`. |
| 138 | +- `repo must be in owner/repo format` → use `owner/repo`, e.g. `octocat/hello-world`. |
98 | 139 |
|
99 | | -For a full environment check, run: |
| 140 | +For a full environment check: |
100 | 141 |
|
101 | 142 | ```bash |
102 | 143 | kagan doctor |
|
0 commit comments