IssueTracker

English | 中文

English

IssueTracker is a local Obsidian plugin workspace for syncing issues from Git-compatible hosts into your vault.

The current implementation is verified against GitCode and GitLab-style issue APIs, including GitLab API v4 and GitCode API v5. It also includes compatibility paths for GitHub and Gitee host layouts, but those paths have not been fully tested yet. If you hit a bug on any host, please open an issue.

What It Does

• Sync issues from selected repositories on supported hosts, or from every repository under a configured organization or group.
• Persist each issue as a normalized Obsidian note under the configured issues folder.
• Mark authors as internal or external by combining the confirmed member directory, repository collaborator data, and a manual whitelist.
• Treat authors as internal when titles match an IR / SR reference or a default workflow marker (【fix】, 【bug】, 【门禁测试】, 门禁测试, 【release】, 【next】, 【需求】), even when the account is not yet in the confirmed directory. Historical closed Issues do not receive first-time ledger rows, but their internal evidence identifies later Issues from the same account.
• Generate a roster-gap Markdown report listing title-evidence accounts missing from the confirmed directory, including reasons and related Issues.
• Classify issues into bug, requirement, or unknown using configurable prefix, keyword, and label rules.
• Generate machine-friendly daily reports and AI-friendly daily briefs.
• Generate a 13-column native-hyperlink XLSX issue ledger. It records the first non-author, non-system comment timestamp and elapsed response time without storing comment text. A tracked Issue that changes from open to closed is shown with a dark row for that sync; retired CSV output is removed after a successful XLSX refresh.
• Generate a separate Markdown reminder when tracked Issues close, retaining the current closed-Issue list for follow-up.
• Notify locally when internal or external Issues are newly discovered. An optional Feishu group-bot webhook sends newly discovered external Issues only; delivery is logged only after the webhook accepts it, so a failed or unrecorded delivery remains pending for a later successful sync.
• Optionally post one configurable reply back to an internal Issue after its configured delay from creation, but only if it remains open and has no non-author comment. The delay defaults to 24 hours and can be set to 0 or any other non-negative number of hours. External Issues are never auto-replied; the first enablement creates a silent baseline instead of replaying historical Issues.
• Persist sync metadata, degraded-sync warnings, and collaborator caches under the configured meta folder.

Default Output Layout

• GitCode Issues/issues/*.md
• GitCode Issues/meta/internal-members.json
• GitCode Issues/meta/issue-closure-state.json
• GitCode Issues/meta/issue-ledger-state.json
• GitCode Issues/meta/issue-notification-state.json
• GitCode Issues/meta/internal-issue-auto-reply-state.json
• GitCode Issues/meta/sync-state.json
• GitCode Issues/reports/issue-ledger.xlsx
• GitCode Issues/reports/internal-member-identity-review.md
• GitCode Issues/reports/issue-close-reminders.md
• GitCode Issues/reports/daily/YYYY-MM-DD.md
• GitCode Issues/reports/daily-brief/YYYY-MM-DD-brief.md

The default output layout still uses GitCode Issues for backward compatibility, but you can change it in settings if you want a host-specific folder name.

Installation

For the release ZIP, extract the issuetracker folder into your vault's .obsidian/plugins/ directory, then enable IssueTracker in Obsidian. The ZIP deliberately does not include data.json; configure your own token and settings in the plugin settings page.

For source-workspace builds:

1. Run npm install once if dependencies are not installed yet.
2. Build the plugin with npm run build.
3. Copy these files into your vault plugin directory .obsidian/plugins/issuetracker/:
   • manifest.json
   • main.js
   • styles.css
   • versions.json
4. Enable IssueTracker in Obsidian.

Configuration

Open the IssueTracker settings tab and configure:

• Git Host URL: historical field name in code, used as the base URL for the configured host; defaults to https://gitcode.com
• API Base URL: defaults to https://gitcode.com/api/v5; override it to match the configured host's API root
• Personal Access Token: token used for API requests against the configured host
• Organization Name: the organization, group, or owner that owns the repositories
• Repository List: one repository per line when you do not sync the whole organization or group
• Sync all organization repositories: automatically discover repositories under the configured organization or group
• Internal User Whitelist: fallback usernames to treat as internal even if collaborator sync is incomplete
• Internal Member Directory: authoritative JSON account-to-name mapping used by ledgers, daily reports, and roster-gap review; listed accounts are confirmed internal
• Issue Ledger Start Month: optional YYYY-MM cutoff. Only issues created in that month or later enter the ledger; changing it resets ledger serial allocation
• Classification Rules: JSON rules for mapping titles or labels into bug / requirement
• Issues Folder, Meta Folder, Reports Folder: output locations inside the vault
• Generate daily reports: write daily summaries and AI briefs after sync
• Show local notifications for new Issues?: show an Obsidian notice for newly discovered internal and external Issues; each Issue is labelled with its author type; enabled by default
• Feishu Bot Webhook: optional Feishu group-bot URL. The plugin posts newly discovered external Issues only; successful delivery is recorded per Issue and pending deliveries retry after later successful syncs. Leave empty for local notices only
• Automatically reply once to internal Issues after their configured delay?: opt-in write-back for internal Issue authors only. After creation plus the configured delay, the Issue is replied to only if it remains open and has no non-author comment. The first successful run after enabling establishes a silent baseline; failed replies remain pending for a later successful sync.
• Internal Issue auto-reply template: the reply body used once per eligible internal Issue. It supports {{repo}}, {{iid}}, {{title}}, {{author}}, {{authorUsername}}, {{url}}, and {{createdAt}}.
• Internal Issue auto-reply delay (hours): delay measured from Issue creation before the reply becomes eligible. It defaults to 24; use 0 for the next successful sync.

The settings page still keeps a legacy API-scope compatibility section from the original importer code path. The primary workflow in this fork is the repository sync path described above.

Usage

• Click the left-ribbon IssueTracker icon to trigger a sync.
• Or run the command palette action Sync IssueTracker.
• If Refresh issues on startup is enabled, the plugin waits 30 seconds after launch before the first automatic sync.
• Automatic refresh runs every 15 minutes by default.
• The first successful sync silently records the current Issue set. Later successful syncs notify for newly discovered internal and external Issues; Feishu delivers newly discovered external Issues only. Failed or degraded syncs do not advance the notification baseline, and an external Issue is removed from the Feishu pending queue only after the webhook responds successfully. Overlapping triggers share one in-progress sync so they cannot duplicate progress notices or compete to write the same generated files.
• When internal auto-reply is enabled, the first successful run silently establishes a baseline. Later successful syncs queue newly discovered internal Issues that remain open without a non-author comment, then post the configured reply once when their creation time plus the configured delay is due; failed write-backs remain pending. External Issues are never auto-replied.

Generated Data

Issue notes are generated artifacts. The current sync flow rewrites normalized issue files and derived reports, so manual edits inside generated notes should be treated as disposable unless you change the output process.

Each normalized issue note includes frontmatter such as:

• createdAt
• updatedAt
• projectPath
• sourceRepo
• authorUsername
• isInternalAuthor
• requestKind
• requestKindMatchedBy
• labels

Dataview Example

TABLE requestKind, isInternalAuthor, authorUsername, sourceRepo
FROM "GitCode Issues/issues"
SORT createdAt DESC

API Reference

API details vary by host. Consult the official REST API documentation for the provider you are configuring:

• GitHub REST API
• Gitee REST API
• GitLab REST API
• GitCode REST API

License

The plugin code is released under the MIT license. See LICENSE.txt.

Reference

This workspace is adapted from the upstream obsidian-gitlab-issues plugin and reoriented around a multi-host issue workflow.

Simplified Chinese

IssueTracker 是一个本地 Obsidian 插件工作区，用来把 Git 代码托管平台上的 issue 同步到你的知识库。

当前实现已经验证了 GitCode 和 GitLab 风格的 issue API，包括 GitLab API v4 和 GitCode API v5。同时也补了 GitHub 和 Gitee 的兼容路径，但这两条路径还没有完整测过；如果你遇到 bug，可以直接提 issue。

它能做什么

• 从指定的仓库同步 issue，或者同步某个组织 / group 下的全部仓库。
• 将每条 issue 规范化后保存到配置的 issues 目录。
• 结合内部成员目录、仓库协作者信息和手工白名单，把作者标记为内部或外部成员。
• 当标题命中 IR / SR 内部编号，或默认内部工作标记 【fix】、【bug】、【门禁测试】、门禁测试、【release】、【next】、【需求】 时，即使作者账号尚未进入成员目录，也按内部人员处理。历史关闭 Issue 不会首次写入台账，但其内部证据会用于识别同一账号后续的 Issue。
• 自动生成“内部人员名单收集待补全报告”，单独列出命中内部标题证据但不在已确认成员目录中的账号、原因和关联 Issue。
• 通过可配置的前缀、关键词和标签规则，把 issue 分类为 bug、requirement 或 unknown。
• 生成便于机器处理的日报，以及适合 AI 消费的日报摘要。
• 生成 13 列 XLSX issue 台账，使用原生超链接，导入腾讯文档后可直接点击。“首次响应时间”取非 Issue 作者、非系统事件的第一条评论时间，只保留时间元数据，不保存评论正文；已追踪 Issue 从 open 变为 closed 的当次同步会以深色整行标记。Excel 写入成功后会清理已废弃的 CSV 台账。
• 在已追踪的 issue 关闭时生成独立 Markdown 提醒，并保留当前关闭 issue 列表便于跟进。
• 对新增内部和外部 Issue 发送本机提醒；可选飞书群机器人只发送新增外部 Issue。飞书只有在 Webhook 成功接收后才记录为已投递，失败或未记录的投递会在后续成功同步时重试。
• 可选地在内部 Issue 创建满设定时长后，若其仍为 open 且没有非作者评论，则自动回写一条回复；延迟默认 24 小时，也可以设置为 0 或其他非负小时数。外部 Issue 不自动回写。首次开启时会静默建立基线，不会重放历史评论；失败的自动回复会保留到后续成功同步重试。
• 将同步元数据、降级同步告警和协作者缓存保存到配置的 meta 目录。

默认输出结构

• GitCode Issues/issues/*.md
• GitCode Issues/meta/internal-members.json
• GitCode Issues/meta/issue-closure-state.json
• GitCode Issues/meta/issue-ledger-state.json
• GitCode Issues/meta/issue-notification-state.json
• GitCode Issues/meta/internal-issue-auto-reply-state.json
• GitCode Issues/meta/sync-state.json
• GitCode Issues/reports/issue-ledger.xlsx
• GitCode Issues/reports/internal-member-identity-review.md
• GitCode Issues/reports/issue-close-reminders.md
• GitCode Issues/reports/daily/YYYY-MM-DD.md
• GitCode Issues/reports/daily-brief/YYYY-MM-DD-brief.md

默认输出结构仍然沿用 GitCode Issues 作为兼容默认值，但你可以在设置里改成适合当前主机的目录名。

安装

使用发布 ZIP 时，将其中的 issuetracker 文件夹解压到你的 vault 的 .obsidian/plugins/ 目录，然后在 Obsidian 中启用 IssueTracker。ZIP 不会包含 data.json，请在插件设置页填写你自己的 token 和同步配置。

从源码工作区构建时：

1. 如果依赖还没安装，先执行一次 npm install。
2. 使用 npm run build 构建插件。
3. 把这些文件复制到你的 vault 插件目录 .obsidian/plugins/issuetracker/：
   • manifest.json
   • main.js
   • styles.css
   • versions.json
4. 在 Obsidian 里启用 IssueTracker。

配置

打开 IssueTracker 的设置页，配置以下内容：

• Git Host URL：代码里沿用的历史字段名，本质上表示当前主机地址；默认是 https://gitcode.com
• API Base URL：默认是 https://gitcode.com/api/v5；需要时可按当前主机的 API 根路径覆盖
• Personal Access Token：用于当前主机 API 请求的 token
• Organization Name：拥有目标仓库的组织、group 或 owner
• Repository List：当你不想同步整个组织或 group 时，每行填写一个仓库
• Sync all organization repositories：自动发现并同步该组织或 group 下的所有仓库
• Internal User Whitelist：当协作者同步不完整时，仍要视为内部成员的用户名白名单
• Internal Member Directory：账号到姓名的权威 JSON 映射，用于台账、日报和名单待补全报告；目录中的账号均视为已确认内部人员
• Issue Ledger Start Month：可选 YYYY-MM 截止月份，只会将该月及之后创建的 issue 写入台账；修改该值会重建台账序号
• Classification Rules：把标题或标签映射到 bug / requirement 的 JSON 规则
• Issues Folder、Meta Folder、Reports Folder：vault 内的输出目录
• Generate daily reports：同步完成后生成日报和 AI 摘要
• 新增 Issue 时本机提醒？：默认开启；对新增的内部和外部 Issue 显示 Obsidian 提示，并标明类型
• 飞书群机器人 Webhook：可选的飞书群机器人地址。插件只会从 Obsidian 直接发送本次新增的外部 Issue；每条成功投递都会记录，未成功投递会在后续成功同步时重试；留空则只保留本机提示
• 内部 Issue 在设定延迟后自动回复一次？：仅对内部 Issue 开启一次性写回；Issue 创建满设定时长后，只有仍为 open 且没有非作者评论时才会回复。
• 内部 Issue 自动回复模板：自动回复正文，支持 {{repo}}、{{iid}}、{{title}}、{{author}}、{{authorUsername}}、{{url}}、{{createdAt}} 占位符。
• 内部 Issue 自动回复延迟（小时）：从 Issue 创建时间开始计时，默认 24 小时；填 0 表示下一次成功同步即可回复。

设置页里仍保留了原始导入器路径中的旧 API scope 兼容区块。这个分支当前的主要工作流是上面这套仓库同步模型。

使用方式

• 点击左侧边栏的 IssueTracker 图标触发同步。
• 或者在命令面板里执行 Sync IssueTracker。
• 如果启用了 Refresh issues on startup，插件会在 Obsidian 启动 30 秒后执行第一次自动同步。
• 默认情况下，自动刷新每 15 分钟执行一次。
• 第一次成功同步只会静默记录当前 Issue 集合；之后的成功同步会提醒新增的内部和外部 Issue，并标明类型。飞书仅投递新增外部 Issue，成功后才从待投递队列移除，失败会在后续成功同步时重试。失败或降级同步不会推进通知基线。重叠的同步触发会复用同一次运行，避免重复进度条和对同一生成文件的竞争写入。
• 开启内部自动回复后，第一次成功同步会静默建立基线；后续成功同步仅将新发现的内部、open、无非作者评论 Issue 进入待处理队列，在创建时间加上配置延迟到期后只回复一次，失败会保留到待处理队列。外部 Issue 不会自动回写。

生成的数据

issue 笔记属于生成产物。当前同步流程会重写规范化的 issue 文件和派生报表，所以除非你同时修改输出流程，否则对生成笔记的手工编辑都应视为可丢弃内容。

每条规范化 issue 笔记都会包含类似下面这些 frontmatter：

• createdAt
• updatedAt
• projectPath
• sourceRepo
• authorUsername
• isInternalAuthor
• requestKind
• requestKindMatchedBy
• labels

Dataview 示例

TABLE requestKind, isInternalAuthor, authorUsername, sourceRepo
FROM "GitCode Issues/issues"
SORT createdAt DESC

API 参考

不同主机的 API 细节不一样，请查看你配置的平台官方 REST API 文档：

• GitHub REST API
• Gitee REST API
• GitLab REST API
• GitCode REST API

许可证

插件代码基于 MIT 协议发布。见 LICENSE.txt。

参考来源

本工作区是在上游 obsidian-gitlab-issues 插件基础上改造的，并重新聚焦到多主机 issue 工作流。