Jira 集成

Jira 集成用于把 Jira 里的项目、issue、epic、状态、评论和附件接入 HiFox。接入后，团队可以继续保留 Jira 中已有的工作流，同时把任务交给 HiFox 里的成员、Agent 或小队处理。

HiFox 里和 Jira 相关的能力主要分成两类：

Jira 导入：把 Jira 里已有的 issue / epic 批量导入到 HiFox；

Jira 同步：把一个 Jira 项目和一个 HiFox Space 绑定，让后续变更在两边同步。

如果你只是想把历史数据迁进 HiFox，从导入开始。
如果你还需要继续和 Jira 双向协作，应该配置 Jira 同步。

Jira 集成能做什么？

Jira 集成可以帮助你：

把 Jira issue 导入为 HiFox 任务；

把 Jira epic 导入或同步为 HiFox 项目；

把 Jira project 绑定到一个 HiFox 空间；

保留 Jira issue 的标题、描述、状态、优先级、负责人、标签、评论、附件、关联关系等上下文；

将 Jira labels 导入为 HiFox 任务标签；

将 Jira issue links 同步为 HiFox 任务关联；

根据需要把 HiFox 中的任务更新写回 Jira。

这样，Jira 可以继续作为外部任务来源，HiFox 则成为成员和 Agent 执行、追踪、协作和 review 的地方。

连接 Jira 前需要准备什么？

连接 Jira 需要一个可以访问目标 Jira 项目的账号，以及对应令牌。

通常需要准备：

Jira 主机名，例如 acme.atlassian.net；

邮箱或用户名；

Jira Cloud 的 Atlassian API token，或 Jira Server / Data Center 的 Personal Access Token（PAT）；

目标 Jira project 的访问权限；

如果要自动安装 webhook，账号需要具备对应 Jira 实例和项目的管理权限。

HiFox 会在连接时验证凭据。令牌只提交一次，会加密保存；接口不会把完整令牌返回给前端，只会显示尾号，方便你确认当前使用的是哪一个令牌。

Jira 导入和 Jira 同步的区别

能力	用途	是否持续同步
Jira 导入	把已有 Jira 数据批量搬到 HiFox。	默认不是持续同步。
Jira 同步	把 Jira project 和 HiFox Space 绑定，后续保持更新。	是。

导入适合迁移历史数据。同步适合保留 Jira 作为外部协作入口，或者让已有 Jira 流程继续运行。

导入时也可以选择“导入后同步”。如果当前组织已经绑定了同一个 Jira 实例，HiFox 可以在导入前为目标 Jira project 和 Space 建立双向同步链接。这样导入进来的 issue 和 epic 会立即带上同步关系，后续变更可以继续同步。

导入 Jira 数据

Jira 导入位于设置里的导入流程。导入向导会引导你完成配置、检查、选择范围、映射状态、映射用户、选择导入选项和确认导入。

1. 选择导入方式

当前推荐方式是通过 Jira API 导入。CSV 导入入口可能会显示为即将支持，但当前主要流程以 API 导入为准。

2. 配置 Jira 连接信息

你需要填写：

Jira 主机名；

邮箱或用户名；

API token 或 PAT；

Jira project key；

可选 JQL；

目标 HiFox Space。

JQL 用于限制导入范围。例如你可以只导入某个组件、某个时间之后创建的 issue，或某一类 issue。

3. 检查导入内容

HiFox 会先读取 Jira 数据并展示预览。

预览中通常会看到：

将导入多少 issue；

将导入多少 epic；

发现多少状态、标签、用户、任务类型和自定义字段；

open issue 与 closed / done issue 的数量；

目标 Space 中是否已经存在同来源的 Jira issue。

这一步只检查，不会创建任务。

4. 选择导入 open 还是 closed issue

你可以选择导入：

open issue；

closed / done issue；

两者都导入。

默认适合导入完整历史。如果你只想先迁移仍在进行中的工作，可以只导入 open issue。

5. 映射状态

Jira 状态会映射到 HiFox 的任务状态。

HiFox 会根据 Jira 状态名称和状态分类给出默认映射。你可以：

使用已有 HiFox 状态；

为某个 Jira 状态创建新的 HiFox 状态；

调整状态所属分类和顺序。

建议在导入前认真检查状态映射。状态映射会影响导入后任务在列表、看板、视图和 Agent 执行流程里的位置。

6. 映射用户

Jira 导入会扫描 assignee、reporter 以及支持的用户类型自定义字段。

你可以选择：

不导入用户；

将 Jira 用户映射到已有 HiFox 成员；

用 Jira 用户邮箱邀请新成员；

跳过某些 Jira 用户，让相关任务保持未分配。

默认更谨慎：不自动导入用户。这样可以避免把历史 Jira 用户批量变成组织成员。需要保留负责人和评论作者信息时，再显式映射用户。

如果你选择用邮箱创建用户，HiFox 会创建或复用对应用户，并发送组织邀请。受邀人接受后，会加入导入目标 Space。

7. 选择导入选项

导入前可以选择一些额外选项：

导入后同步：如果已绑定同一个 Jira 实例，可以为目标 Jira project 和 Space 建立同步；

导入 Sprint：导入 Jira Sprint 信息；

切换到 Jira Sprint 模式：当目标 Space 仍使用自动迭代模式时，可以切换为手动 Jira 模式；

添加 Migrated 标签：默认给导入的任务添加 Migrated 标签；

覆盖导入：重新导入时，用 Jira 中的数据覆盖已导入任务的可变字段。

如果不确定，建议先保留默认选项。Migrated 标签对后续筛选、检查和回滚都很有帮助。

8. 查看导入进度

导入开始后，HiFox 会显示导入任务的进度，包括总数、已完成数量、跳过数量和失败项。

导入过程中可以取消。取消后，已经创建的任务会保留；如果需要清理，可以使用导入历史中的回滚能力。

导入完成后，可以进入目标 Space 查看导入任务。通常可以用 Migrated 标签筛选导入结果。

导入会创建哪些 HiFox 数据？

导入 Jira issue 时，HiFox 会尽量保留 Jira 上下文。

常见结果包括：

Jira issue → HiFox 任务；

Jira epic → HiFox 项目；

Jira issue type → HiFox 任务类型；

Jira status → HiFox 任务状态 / 工作流状态；

Jira labels → HiFox 组织标签；

Jira watchers → 任务关注者；

Jira comments → 任务评论；

Jira attachments → 任务附件；

Jira issue links → 任务关联；

Jira sub-task / parent 关系 → HiFox 子任务关系；

Jira Sprint → HiFox 迭代相关数据。

不是每个 Jira 字段都会一比一同步。Jira 中某些高度自定义或只在特定项目配置中存在的字段，可能会作为自定义字段导入，或在当前版本中被跳过。

回滚导入

导入历史会记录每次 Jira 导入任务。

如果导入后发现范围选错、映射不合适，或目标 Space 不正确，可以在允许时间窗口内回滚导入。回滚会删除这次导入创建的任务和项目，并标记导入记录为已回滚。

注意：回滚只清理 HiFox 中这次导入产生的数据，不会删除 Jira 里的 issue 或 epic。

配置 Jira 同步

Jira 同步位于外部应用集成中的 Jira 设置。

配置一般分两步：

绑定 Jira 实例；

创建 Jira project 与 HiFox Space 的同步链接。

绑定 Jira 实例

在 Jira 集成页点击设置或管理，填写：

主机名；

邮箱或用户名；

API token 或 PAT。

绑定成功后，HiFox 会保存这个组织级 Jira 连接，并缓存 Jira project 列表。之后可以手动刷新 Jira 项目元数据。

组织 owner / admin 可以绑定、更新凭据、刷新项目列表或断开 Jira。

创建 Jira 同步链接

一个同步链接会把一个 Jira project 绑定到一个 HiFox Space。

创建链接时需要选择：

Jira project；

HiFox Space；

同步方向；

issue 状态和项目状态映射。

一个 Jira project 只能主动链接到一个 Space；但多个 Jira project 可以链接到同一个 Space。

Jira project 和 Space 在链接创建后不能直接改成另一个目标。如果选错，需要删除链接后重新创建。

同步方向

Jira 同步支持两种方向：

方向	含义
Jira → HiFox	Jira 中的 issue 和 epic 同步到 HiFox；HiFox 中的部分更新也会写回已同步的 Jira 项。
双向	Jira 与 HiFox 之间双向同步；在 HiFox 中创建的新任务或项目也可以创建到 Jira。

如果团队仍把 Jira 作为主要入口，可以先使用 Jira → HiFox。
如果团队希望在 HiFox 中创建、拆分、分配任务，同时保持 Jira 更新，可以使用双向同步。

会同步哪些字段？

当前 Jira 同步重点覆盖任务、项目和协作中最常用的字段。

常见同步内容包括：

标题 / summary；

描述；

优先级；

状态；

负责人；

标签；

截止日期；

预估；

Jira epic 与 HiFox 项目；

评论；

附件；

issue link / 任务关联。

状态同步依赖状态映射。如果某个 HiFox 状态没有映射到 Jira 状态，状态更新可能不会写回 Jira，并会在任务或项目的 Jira 同步状态中显示警告。

预估会根据 Space 的估算方式和 Jira 项目配置写入。Story Points 会写入 Jira 的 Story Points 字段；时间估算会写入 Jira original estimate，并使用 Jira 实例的工作日历换算工作日和小时。

个人 Jira 账号

组织级 Jira 绑定使用的是共享集成凭据，适合执行同步、创建 issue、更新字段和安装 webhook。

如果你希望从 HiFox 写到 Jira 的评论尽量以你自己的 Jira 身份发布，可以绑定个人 Jira 账号。

绑定个人 Jira 账号后：

你在 HiFox 中发布到 Jira 的评论，会优先使用你的个人 Jira 凭据；

assignee、creator / reporter、project lead 等 Jira 身份字段可以更准确映射；

如果个人凭据失效，评论会回退为组织级集成账号发布。

个人 Jira 账号只影响你的身份映射和评论身份，不会断开或修改组织级 Jira 同步。

在任务中查看 Jira 同步状态

已经和 Jira 同步的任务，会在任务详情里显示 Jira 同步信息。

常见状态包括：

已同步；

待同步；

同步警告；

同步错误；

远端已删除；

存在冲突。

如果同步失败，可以查看错误说明。部分失败可以重试，例如 Jira 必填字段、权限、状态映射或凭据问题修复后，再重新触发同步。

任务详情里也可以打开对应 Jira issue。需要停止单个任务和 Jira 的关系时，管理员可以断开该任务的 Jira 同步链接；断开不会删除 HiFox 任务或 Jira issue。

断开 Jira 或删除同步链接

断开 Jira 实例会停用这个组织的 Jira 绑定，并停用相关 Jira project 与 Space 的同步链接。后续同步会停止。

删除某个同步链接，只会停止这个 Jira project 与 Space 之间的后续同步。

这两种操作都不会删除：

Jira issue；

Jira epic；

HiFox 任务；

HiFox 项目；

已经导入或同步过的评论和附件。

如果只是 Jira token 过期，建议更新凭据，而不是断开整个 Jira 集成。

权限和安全

通常规则是：

组织 owner / admin 可以绑定 Jira、更新凭据、创建或删除同步链接；

普通成员可以查看已有 Jira 同步状态；

成员可以绑定自己的个人 Jira 账号；

Jira token 会加密保存，完整 token 不会在接口中返回；

Jira 导入时使用的临时凭据只用于本次导入流程，任务完成后不会作为普通可读配置展示。

建议为 Jira 集成准备权限合适的服务账号或管理员账号，并定期轮换 token。

最佳实践

先小范围导入

第一次迁移时，不建议直接导入整个 Jira 历史。可以先用 JQL 限制一个项目、一个组件或最近一批 issue，确认状态、用户、标签和任务类型映射符合预期后，再扩大范围。

先检查状态映射

状态映射会影响看板、视图和同步写回。导入或创建同步链接前，建议先确认 Jira 状态和 HiFox 状态的含义一致。

用 Migrated 标签验收导入结果

导入时保留 Migrated 标签，可以在任务列表里快速筛选这批任务，检查数量、状态、负责人、评论和附件是否符合预期。

不确定时先用 Jira → HiFox

如果团队还没有决定是否在 HiFox 中创建 Jira issue，可以先使用 Jira → HiFox。等团队确认 HiFox 中的任务流程稳定后，再切换到双向同步。

让 Agent 读取同步后的任务上下文

Jira 导入或同步后的任务会保留描述、评论、附件、标签和关联任务。把这些任务委派给 Agent 前，建议补充清楚目标和验收标准，让 Agent 不只是读取历史上下文，还知道下一步要做什么。

常见问题

Jira Cloud 和 Jira Server / Data Center 都支持吗？

支持。Jira Cloud 通常使用邮箱和 Atlassian API token；Jira Server / Data Center 通常使用用户名和 PAT。

导入会删除 Jira 里的 issue 吗？

不会。导入只在 HiFox 中创建任务、项目和相关数据，不会删除 Jira 数据。

同步链接删除后，已有任务还在吗？

还在。删除同步链接只停止后续同步，不删除已经存在的 HiFox 任务或 Jira issue。

为什么绑定成功后看不到 Jira project？

可能是账号没有访问项目的权限，或者项目元数据还没有刷新。可以在 Jira 集成页刷新 Jira 项目列表，并确认凭据账号能在 Jira 中浏览对应项目。

为什么状态没有同步回 Jira？

通常是状态映射缺失、Jira 工作流不允许直接切换到目标状态，或 Jira 项目有必填字段 / workflow rule 拦截。先检查同步状态里的错误说明，再调整状态映射或 Jira 工作流配置。

评论一定会同步到 Jira 吗？

不是。只有通过支持“发布到 Jira”的评论入口发布的顶层成员评论，才会写回 Jira。普通本地评论、回复和 Agent 评论会保留在 HiFox 任务中。

附件会重复上传吗？

HiFox 会记录 Jira 附件的远端 ID，避免已从 Jira 拉取或已经上传过的附件再次上传。

我应该用导入还是同步？

如果目标是一次性迁移历史数据，用导入。
如果目标是让 Jira 和 HiFox 在之后继续保持更新，用同步。
如果既要迁移历史，又要保持后续更新，可以先配置 Jira 绑定，再导入时开启“导入后同步”。

Jira 同步故障排查

当任务或项目顶部出现 Jira 同步提示时，先看提示标题和说明，再到 Jira 集成设置、同步链接配置或对应 Jira issue 中处理根因。修复后，可以在任务或项目详情中重试同步。

Jira 权限或认证失败

已与 Jira 同步 同步警告

Jira 权限或认证失败。请更新 Jira 凭据，并确认该账号可浏览项目并创建或编辑 issue。

这通常表示当前组织级 Jira 凭据、个人 Jira 凭据或账号权限不可用。

可以按顺序检查：

在 Jira 集成页更新组织级 Jira token；

确认该账号可以在 Jira 中浏览目标项目，并有创建或编辑 issue 的权限；

如果失败发生在评论同步，确认评论发布者是否需要绑定或更新个人 Jira 账号；

更新凭据后重试同步。

未找到 Jira 条目

已与 Jira 同步 同步警告

未找到 Jira 条目。请恢复该 Jira issue，或先断开此同步链接再重试。

这通常表示 HiFox 中的同步任务仍在，但对应的 Jira issue 已被删除、移动、归档，或当前 Jira 账号已经无法访问。

可以按顺序检查：

从任务详情打开 Jira issue，确认 Jira 中是否仍能访问；

如果 issue 被误删或归档，先在 Jira 中恢复；

如果只是权限变化，恢复集成账号对该项目或 issue 的访问权限；

如果不再需要同步，断开这个任务和 Jira issue 的同步链接。

Jira Epic 类型不可用

已与 Jira 同步 同步警告

Jira Epic 类型不可用。请为关联的 Jira 项目启用 Epic 类型，或将链接切换为单向同步。

这通常发生在同步项目或 epic 时：目标 Jira 项目没有可用的 Epic issue type，或项目配置不允许创建 Epic。

可以按顺序检查：

在 Jira 项目设置中确认 Epic 类型已启用；

确认集成账号有创建 Epic 的权限；

如果当前 Jira 项目不使用 Epic，改用单向同步或避免把 HiFox 项目写回为 Jira Epic；

调整后重新触发同步。

Jira 必填字段拦截了同步

已与 Jira 同步 同步警告

Jira 必填字段拦截了同步。请移除此处未同步的 Jira 必填字段，或在 Jira 中为其设置项目默认值。

这通常表示 Jira 项目的创建或编辑界面中有 HiFox 当前不会写入的必填字段，例如组件、版本、自定义字段或安全级别。

可以按顺序检查：

查看 Jira 返回的具体字段错误；

在 Jira 项目配置中移除这类字段的必填要求，或给字段设置默认值；

确认该字段出现在 Jira 的创建或编辑界面中，且集成账号有权限写入；

修复 Jira 配置后重试同步。

Jira 工作流或字段约束拦截了同步

已与 Jira 同步 同步警告

Jira 工作流或字段约束拦截了同步。请检查此项目的 Jira 工作流规则、界面、字段上下文及状态映射。

这就是常见的“Jira 工作流或字段约束拦截了同步”提示。它通常表示 HiFox 试图更新状态或字段时，Jira 工作流规则、界面配置、字段上下文或状态映射不允许这次变更。

可以按顺序检查：

检查同步链接里的状态映射，确认目标 HiFox 状态映射到了正确的 Jira 状态；

在 Jira 工作流中确认当前状态能直接流转到目标状态；

检查 workflow validator、condition、post function 是否限制了字段、角色或流转路径；

检查 Jira issue 的编辑界面、字段上下文和必填规则；

调整 Jira 配置或状态映射后重试同步。

Jira webhook 或项目范围需检查

已与 Jira 同步 同步警告

Jira webhook 或项目范围需检查。请检查关联的 Jira 项目与同步 webhook 的 JQL。导入 JQL 不影响后续的同步 webhook。

这通常表示 Jira 到 HiFox 的后续更新没有进入同步链路，常见原因是 webhook JQL、项目范围或 Jira 项目绑定不匹配。

可以按顺序检查：

确认 Jira project 已经和正确的 HiFox Space 建立同步链接；

检查 Jira webhook 的 JQL 是否覆盖目标项目和 issue 范围；

确认导入时使用的 JQL 只影响导入范围，不会自动限制后续同步 webhook；

如果项目范围变更过，刷新 Jira 项目元数据或重新创建同步链接。

正在显示按分类的默认状态映射

已与 Jira 同步 同步警告

正在显示按分类的默认状态映射。无法加载实时 Jira 状态，因此各状态按其分类映射。请重新绑定 Jira 凭据以选择确切的 Jira 状态。

这通常表示 HiFox 暂时无法读取 Jira 的实时状态列表，只能根据 Jira 状态分类显示默认映射。

可以按顺序检查：

更新或重新绑定 Jira 凭据；

确认集成账号可以读取 Jira 项目状态和工作流信息；

刷新 Jira 项目元数据；

重新打开状态映射配置，选择准确的 Jira 状态。

评论使用了集成账号

已与 Jira 同步 同步警告

评论使用了集成账号。若希望评论以你的身份发布，请绑定或更新你的个人 Jira 账号。

这通常表示当前成员没有可用的个人 Jira 账号，或个人 Jira 凭据失效。HiFox 会回退为组织级集成账号发布 Jira 评论。

可以按顺序检查：

成员在个人设置中绑定或更新自己的 Jira 账号；

确认个人 Jira 账号可以浏览并评论目标 issue；

如果团队接受统一身份发布评论，也可以继续使用集成账号；

重新发布需要同步到 Jira 的评论。

Jira 附件同步需要关注

已与 Jira 同步 同步警告

Jira 附件同步需要关注。请检查附件大小与 Jira 文件权限后重试。

这通常表示附件上传或读取失败，常见原因包括附件过大、Jira 附件权限不足、Jira 项目禁用了附件，或网络请求失败。

可以按顺序检查：

确认 Jira 项目允许上传附件；

确认集成账号有读取和上传附件的权限；

检查附件大小是否超过 Jira 或组织配置限制；

删除或压缩异常附件后重试同步。

如果提示不是以上类型，而是泛化的“Jira 写入失败”，通常需要查看同步提示里的 Jira 原始错误，再按字段、权限、工作流或附件方向继续排查。

Jira 集成能做什么？#

连接 Jira 前需要准备什么？#

Jira 导入和 Jira 同步的区别#

导入 Jira 数据#

1. 选择导入方式#

2. 配置 Jira 连接信息#

3. 检查导入内容#

4. 选择导入 open 还是 closed issue#

5. 映射状态#

6. 映射用户#

7. 选择导入选项#

8. 查看导入进度#

导入会创建哪些 HiFox 数据？#

回滚导入#

配置 Jira 同步#

绑定 Jira 实例#

创建 Jira 同步链接#

同步方向#

会同步哪些字段？#

个人 Jira 账号#

在任务中查看 Jira 同步状态#

断开 Jira 或删除同步链接#

权限和安全#

最佳实践#

先小范围导入#

先检查状态映射#

用 Migrated 标签验收导入结果#

不确定时先用 Jira → HiFox#

让 Agent 读取同步后的任务上下文#

常见问题#

Jira Cloud 和 Jira Server / Data Center 都支持吗？#

导入会删除 Jira 里的 issue 吗？#

同步链接删除后，已有任务还在吗？#

为什么绑定成功后看不到 Jira project？#

为什么状态没有同步回 Jira？#

评论一定会同步到 Jira 吗？#

附件会重复上传吗？#

我应该用导入还是同步？#

Jira 同步故障排查#

Jira 权限或认证失败#

未找到 Jira 条目#

Jira Epic 类型不可用#

Jira 必填字段拦截了同步#

Jira 工作流或字段约束拦截了同步#

Jira webhook 或项目范围需检查#

正在显示按分类的默认状态映射#

评论使用了集成账号#

Jira 附件同步需要关注#

Jira 集成能做什么？

连接 Jira 前需要准备什么？

Jira 导入和 Jira 同步的区别

导入 Jira 数据

1. 选择导入方式

2. 配置 Jira 连接信息

3. 检查导入内容

4. 选择导入 open 还是 closed issue

5. 映射状态

6. 映射用户

7. 选择导入选项

8. 查看导入进度

导入会创建哪些 HiFox 数据？

回滚导入

配置 Jira 同步

绑定 Jira 实例

创建 Jira 同步链接

同步方向

会同步哪些字段？

个人 Jira 账号

在任务中查看 Jira 同步状态

断开 Jira 或删除同步链接

权限和安全

最佳实践

先小范围导入

先检查状态映射

用 Migrated 标签验收导入结果

不确定时先用 Jira → HiFox

让 Agent 读取同步后的任务上下文

常见问题

Jira Cloud 和 Jira Server / Data Center 都支持吗？

导入会删除 Jira 里的 issue 吗？

同步链接删除后，已有任务还在吗？

为什么绑定成功后看不到 Jira project？

为什么状态没有同步回 Jira？

评论一定会同步到 Jira 吗？

附件会重复上传吗？

我应该用导入还是同步？

Jira 同步故障排查

Jira 权限或认证失败

未找到 Jira 条目

Jira Epic 类型不可用

Jira 必填字段拦截了同步

Jira 工作流或字段约束拦截了同步

Jira webhook 或项目范围需检查

正在显示按分类的默认状态映射

评论使用了集成账号

Jira 附件同步需要关注