Jira Cloud Provider | 更夫 Gengfu

关于本页

本页介绍更夫所基于的开源内核 Keep 的通用能力。更夫在其上提供国内化增强：钉钉/企业微信/飞书通知、国产大模型接入、LDAP 认证与值班管理。部署与上手请看快速上手。

认证

此提供商需要身份验证。

email: Atlassian Jira 电子邮件（必需：True，敏感：False）
api_token: Atlassian Jira API 令牌（必需：True，敏感：True）
host: Atlassian Jira 主机（必需：True，敏感：False）
ticket_creation_url: 创建新工单的 URL（可选，如果未提供将使用默认值）（必需：False，敏感：False）

某些范围可能需要才能通过提供商执行特定操作或查询。以下是相关范围及其用例的摘要：

BROWSE_PROJECTS: 浏览 Jira 项目（强制）
CREATE_ISSUES: 创建 Jira 问题（强制）
CLOSE_ISSUES: 关闭 Jira 问题
EDIT_ISSUES: 编辑 Jira 问题
DELETE_ISSUES: 删除 Jira 问题
MODIFY_REPORTER: 修改 Jira 问题报告人
TRANSITION_ISSUES: 转换 Jira 问题

在工作流中

此提供商可用于工作流。

作为"步骤"来查询数据，示例：

yaml

steps:
    - name: Query jira
      provider: jira
      config: "{{ provider.my_provider_name }}"
      with:
        ticket_id: {value}  # 问题的工单 ID，可选。
        board_id: {value}  # 问题的看板 ID。

作为"操作"来进行更改或更新数据，示例：

yaml

actions:
    - name: Query jira
      provider: jira
      config: "{{ provider.my_provider_name }}"
      with:
        summary: {value}  # 问题的摘要。
        description: {value}  # 问题的描述。
        issue_type: {value}  # 问题的类型。
        project_key: {value}  # 问题的项目键。
        board_name: {value}  # 问题的看板名称。
        issue_id: {value}  # 问题的 ID。
        labels: {value}  # 问题的标签。
        components: {value}  # 问题的组件。
        custom_fields: {value}  # 问题的自定义字段。
        transition_to: {value}  # 可选的转换名称（例如 "Done"、"Resolved"），在更新/创建后应用。

请查看以下工作流示例：

连接 Provider

前往 https://id.atlassian.com/manage-profile/security/api-tokens 创建 API token，生成的 token 需要传递给 Jira 认证。
从相应看板的 URL 中获取 host 和 board_id。
从项目 > 设置 > 详情中获取 project_key。
email 与您的账户邮箱相同。

自动转换工作流

Jira provider 支持在告警状态变更时自动转换工单。这有助于保持 Jira 看板与告警状态同步，例如在告警解决时自动关闭工单。

前置条件

在 Keep 中配置 Jira Cloud provider
确保您的 Jira 用户具有 TRANSITION_ISSUES 权限
了解您的 Jira 看板名称和期望的转换状态名称

工作流 1：告警时创建 Jira 工单

此工作流在告警触发时创建 Jira 工单，但仅在尚未创建工单时才会创建。

yaml

workflow:
  id: jira-create-ticket-on-alert
  name: Create Jira Ticket on Alert
  description: Create Jira ticket when alert fires
  disabled: false
  triggers:
    - type: alert
      cel: status == "firing"
  actions:
    - name: jira-action
      if: "not '{{ alert.ticket_id }}'"
      provider:
        type: jira
        config: "{{ providers.JiraCloud }}"
        with:
          board_name: YOUR_BOARD_NAME  # Change this to your board name
          issue_type: Task  # Or Bug, Story, etc.
          summary: "{{ alert.name }} - {{ alert.description }}"
          description: |
            "This ticket was created automatically by Keep.

            Alert Details:
            {code:json}
            {{ alert }}
            {code}"
          enrich_alert:
            - key: ticket_type
              value: jira
            - key: ticket_id
              value: results.issue.key
            - key: ticket_url
              value: results.ticket_url

要点：

if: "not '{{ alert.ticket_id }}'" - 仅在工单不存在时创建
enrich_alert - 将工单 ID、类型和 URL 存储在告警中以供后续使用
工单以默认状态创建（通常为"To Do"或"Open"）

工作流 2：告警解决时将工单转换至 Done

此工作流在告警解决时更新现有 Jira 工单并将其转换至"Done"状态。

yaml

workflow:
  id: jira-transition-on-resolved
  name: Transition Jira Ticket to Done
  description: Close Jira ticket when alert is resolved
  disabled: false
  triggers:
    - type: alert
      cel: status == "resolved"
  actions:
    - name: jira-action
      provider:
        type: jira
        config: "{{ providers.JiraCloud }}"
        with:
          issue_id: "{{ alert.ticket_id }}"
          summary: "{{ alert.name }} - {{ alert.description }} (resolved)"
          description: |
            "Alert has been resolved automatically by Keep.

            Resolved at: {{ alert.lastReceived }}

            Original Alert Details:
            {code:json}
            {{ alert }}
            {code}"
          transition_to: Done  # Change to your workflow's status name

要点：

使用 issue_id: "{{ alert.ticket_id }}" 从富化告警数据中获取
transition_to: Done - 将工单转换至指定状态
无需 if 条件 - 如果告警没有 ticket_id，操作将直接失败而不会影响其他流程

可用的转换名称

常见的 Jira 转换名称（因工作流而异）：

Done
Resolved
Closed
In Progress
To Do
Canceled

如何查找转换名称：

进入 Jira 项目设置
导航至工作流
检查工作流中的可用状态
在 transition_to 参数中使用精确的状态名称（不区分大小写）

错误处理

如果您指定了无效的转换名称，Jira provider 将返回一条错误消息，列出该工单的所有可用转换：

Transition 'Invalid' not found. Available transitions: To Do, In Progress, Done, Closed

示例：三状态工作流

您也可以创建中间转换：

yaml

# Workflow 3: Move to In Progress when acknowledged
workflow:
  id: jira-transition-in-progress
  name: Transition to In Progress
  description: Move ticket to In Progress when alert is acknowledged
  disabled: false
  triggers:
    - type: alert
      cel: status == "acknowledged"
  actions:
    - name: jira-action
      provider:
        type: jira
        config: "{{ providers.JiraCloud }}"
        with:
          issue_id: "{{ alert.ticket_id }}"
          summary: "{{ alert.name }} - In Progress"
          description: "Alert acknowledged and being worked on."
          transition_to: In Progress

测试

创建触发第一个工作流的告警

验证 Jira 工单已创建
检查告警是否具有 ticket_id、ticket_type 和 ticket_url 字段

解决告警以触发第二个工作流

验证现有工单已更新（未创建新工单）
检查工单状态是否已更改为"Done"

检查 Keep UI 中的日志以获取任何错误或调试信息

故障排除

问题：工作流创建了新工单而不是更新现有工单

原因： 缺少 issue_id 参数或告警没有 ticket_id。

解决方案： 确保第一个工作流使用 ticket_id 富化告警，第二个工作流通过 issue_id: "{{ alert.ticket_id }}" 使用它。

问题：转换失败并显示"Transition 'X' not found"

原因： 转换名称与 Jira 工作流不匹配。

解决方案： 查看错误消息了解可用转换，并相应更新 transition_to 参数。

问题：转换时权限被拒绝

原因： 您的 Jira 用户没有 TRANSITION_ISSUES 权限。

解决方案： 在 Jira 项目设置中授予必要的权限。

高级功能

配置变量

您可以使用 Keep 的配置变量使工作流更加灵活：

yaml

consts:
  JIRA_BOARD: "ALERTS"
  JIRA_DONE_STATUS: "Done"
  JIRA_ISSUE_TYPE: "Task"

# Then use in workflows:
board_name: "{{ consts.JIRA_BOARD }}"
transition_to: "{{ consts.JIRA_DONE_STATUS }}"
issue_type: "{{ consts.JIRA_ISSUE_TYPE }}"

自定义字段

您还可以在创建或更新工单时设置自定义字段：

yaml

with:
  issue_id: "{{ alert.ticket_id }}"
  summary: "Alert resolved"
  custom_fields:
    customfield_10001: "High"
    customfield_10002: "Production"
  transition_to: Done

标签和组件

yaml

with:
  board_name: YOUR_BOARD_NAME
  summary: "{{ alert.name }}"
  description: "{{ alert.description }}"
  labels:
    - alert
    - automated
    - critical
  components:
    - Monitoring
    - Infrastructure

Kubernetes

keep alert

keep provider

keep workflow

keep workflow runs

keep mappings

keep extractions

认证

在工作流中

连接 Provider

自动转换工作流

前置条件

工作流 1：告警时创建 Jira 工单

工作流 2：告警解决时将工单转换至 Done

可用的转换名称

错误处理

示例：三状态工作流

测试

故障排除

问题：工作流创建了新工单而不是更新现有工单

问题：转换失败并显示"Transition 'X' not found"

问题：转换时权限被拒绝

高级功能

配置变量

自定义字段

标签和组件

注意事项

相关链接

keep workflow runs

认证 ​

在工作流中 ​

连接 Provider ​

自动转换工作流 ​

前置条件 ​

工作流 1：告警时创建 Jira 工单 ​

工作流 2：告警解决时将工单转换至 Done ​

可用的转换名称 ​

错误处理 ​

示例：三状态工作流 ​

测试 ​

故障排除 ​

问题：工作流创建了新工单而不是更新现有工单 ​

问题：转换失败并显示"Transition 'X' not found" ​

问题：转换时权限被拒绝 ​

高级功能 ​

配置变量 ​

自定义字段 ​

标签和组件 ​

注意事项 ​

相关链接 ​

认证

在工作流中

连接 Provider

自动转换工作流

前置条件

工作流 1：告警时创建 Jira 工单

工作流 2：告警解决时将工单转换至 Done

可用的转换名称

错误处理

示例：三状态工作流

测试

故障排除

问题：工作流创建了新工单而不是更新现有工单

问题：转换失败并显示"Transition 'X' not found"

问题：转换时权限被拒绝

高级功能

配置变量

自定义字段

标签和组件

注意事项

相关链接