issues-helper/README.zh-CN.md

<p align="center">
  <a href="https://actions-cool.github.io/issues-helper/">
    <img width="200" src="https://gw.alipayobjects.com/mdn/rms_f97235/afts/img/A*8xDgSL-O6O4AAAAAAAAAAAAAARQnAQ">
  </a>
</p>

<h1 align="center">🤖 Issues 助手</h1>

<div align="center">

一个轻松帮你自动管理 issues 的 GitHub Action

[![](https://img.shields.io/github/actions/workflow/status/actions-cool/issues-helper/ci.yml?branch=main&style=flat-square)](https://github.com/actions-cool/issues-helper/actions)
[![](https://img.shields.io/badge/marketplace-issues--helper-red?style=flat-square)](https://github.com/marketplace/actions/issues-helper)
![](https://img.shields.io/github/languages/top/actions-cool/issues-helper?color=%2308979c&style=flat-square)
[![dumi](https://img.shields.io/badge/docs%20by-dumi-blue?style=flat-square)](https://github.com/umijs/dumi)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)

[![](https://img.shields.io/github/stars/actions-cool/issues-helper?style=flat-square)](https://github.com/actions-cool/issues-helper/stargazers)
[![](https://img.shields.io/github/v/release/actions-cool/issues-helper?style=flat-square&color=orange)](https://github.com/actions-cool/issues-helper/releases)
[![](https://img.shields.io/badge/discussions-on%20github-blue?style=flat-square&color=%23ff7875)](https://github.com/actions-cool/issues-helper/discussions)
[![](https://img.shields.io/github/license/actions-cool/issues-helper?style=flat-square)](https://github.com/actions-cool/issues-helper/blob/main/LICENSE)

</div>

[English](README.md) | 简体中文

## 🔗 链接

- [在线文档](https://actions-cool.github.io/issues-helper/)
- [在线文档 v2 版本](https://actions-cool.github.io/issues-helper-2.x/)
- [更新日志](./CHANGELOG.md)

## 😎 为什么用 GitHub Action？

1. 完全免费
2. 全自动操作
3. 托管于 GitHub 服务器，只要 GitHub 不宕机，它就不受影响

> Private 项目每月有 2000 次的限制，[具体查看](https://github.com/settings/billing)。Public 项目无限制。

## 谁在使用？

欢迎在 [**这里**](https://github.com/actions-cool/issues-helper/issues/6) 留言。

<table>
<tr>
  <td align="center" width="180">
    <a href="https://github.com/ant-design/ant-design">
      <img src="https://avatars1.githubusercontent.com/u/12101536?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/ant-design-blazor/ant-design-blazor">
      <img src="https://user-images.githubusercontent.com/29775873/129505619-5abddb68-8663-4c71-b7d2-049c716aab26.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/ant-design/ant-design-mobile">
      <img src="https://gw.alipayobjects.com/zos/bmw-prod/b874caa9-4458-412a-9ac6-a61486180a62.svg" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/vueComponent/ant-design-vue">
      <img src="https://avatars1.githubusercontent.com/u/32120805?s=200&v=4" width="46"/>
    </a>
  </td>
</tr>
<tr>
  <td align="center" width="180"><a href="https://github.com/ant-design/ant-design">ant-design</a></td>
  <td align="center" width="180"><a href="https://github.com/ant-design-blazor/ant-design-blazor">ant-design-blazor</a></td>
  <td align="center" width="180"><a href="https://github.com/ant-design/ant-design-mobile">ant-design-mobile</a></td>
  <td align="center" width="180"><a href="https://github.com/vueComponent/ant-design-vue">ant-design-vue</a></td>
</tr><tr>
  <td align="center" width="180">
    <a href="https://github.com/twbs/bootstrap">
      <img src="https://getbootstrap.com/docs/5.1/assets/brand/bootstrap-logo-shadow.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/umijs/dumi">
      <img src="https://avatars1.githubusercontent.com/u/33895495?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/electron/electron">
      <img src="https://avatars.githubusercontent.com/u/13409222?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/element-plus/element-plus">
      <img src="https://avatars.githubusercontent.com/u/68583457" width="46"/>
    </a>
  </td>
</tr>
<tr>
  <td align="center" width="180"><a href="https://github.com/twbs/bootstrap">bootstrap</a></td>
  <td align="center" width="180"><a href="https://github.com/umijs/dumi">dumi</a></td>
  <td align="center" width="180"><a href="https://github.com/electron/electron">electron</a></td>
  <td align="center" width="180"><a href="https://github.com/element-plus/element-plus">element-plus</a></td>
</tr><tr>
  <td align="center" width="180">
    <a href="https://github.com/alibaba/formily">
      <img src="https://img.alicdn.com/imgextra/i2/O1CN01Kq3OHU1fph6LGqjIz_!!6000000004056-55-tps-1141-150.svg" width=""/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/vuejs/jsx-next">
      <img src="https://avatars.githubusercontent.com/u/6128107?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/mui/material-ui">
      <img src="https://avatars.githubusercontent.com/u/33663932?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/TuSimple/naive-ui">
      <img src="https://www.naiveui.com/assets/naivelogo-XQ1U1Js8.svg" width="46"/>
    </a>
  </td>
</tr>
<tr>
  <td align="center" width="180"><a href="https://github.com/alibaba/formily">formily</a></td>
  <td align="center" width="180"><a href="https://github.com/vuejs/jsx-next">jsx-next</a></td>
  <td align="center" width="180"><a href="https://github.com/mui/material-ui">material-ui</a></td>
  <td align="center" width="180"><a href="https://github.com/TuSimple/naive-ui">naive-ui</a></td>
</tr><tr>
  <td align="center" width="180">
    <a href="https://github.com/jdf2e/nutui">
      <img src="https://img14.360buyimg.com/imagetools/jfs/t1/167902/2/8762/791358/603742d7E9b4275e3/e09d8f9a8bf4c0ef.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/prettier/prettier">
      <img src="https://user-images.githubusercontent.com/29775873/129505900-ca248179-2435-429d-9fd3-779206bcd899.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/react-component">
      <img src="https://avatars3.githubusercontent.com/u/9441414?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/lijinke666/react-music-player">
      <img src="https://user-images.githubusercontent.com/29775873/129506058-b0d8c741-f73a-496c-98de-7db2fb586db7.png" width="46"/>
    </a>
  </td>
</tr>
<tr>
  <td align="center" width="180"><a href="https://github.com/jdf2e/nutui">nutui</a></td>
  <td align="center" width="180"><a href="https://github.com/prettier/prettier">prettier</a></td>
  <td align="center" width="180"><a href="https://github.com/react-component">react-component</a></td>
  <td align="center" width="180"><a href="https://github.com/lijinke666/react-music-player">react-music-player</a></td>
</tr><tr>
  <td align="center" width="180">
    <a href="https://github.com/antvis/S2">
      <img src="https://gw.alipayobjects.com/mdn/rms_56cbb2/afts/img/A*TI8XSK3W0EkAAAAAAAAAAAAAARQnAQ" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/nolimits4web/swiper">
      <img src="https://user-images.githubusercontent.com/29775873/156721728-3b0021ea-6932-4a77-a104-2e0bad97346e.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/umijs/umi">
      <img src="https://avatars1.githubusercontent.com/u/33895495?s=200&v=4" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/vitejs/vite">
      <img src="https://avatars.githubusercontent.com/u/65625612?s=200&v=4" width="46"/>
    </a>
  </td>
</tr>
<tr>
  <td align="center" width="180"><a href="https://github.com/antvis/S2">S2</a></td>
  <td align="center" width="180"><a href="https://github.com/nolimits4web/swiper">swiper</a></td>
  <td align="center" width="180"><a href="https://github.com/umijs/umi">umi</a></td>
  <td align="center" width="180"><a href="https://github.com/vitejs/vite">vite</a></td>
</tr><tr>
  <td align="center" width="180">
    <a href="https://github.com/vitest-dev/vitest">
      <img src="https://user-images.githubusercontent.com/11247099/145112184-a9ff6727-661c-439d-9ada-963124a281f7.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/AttoJS/vue-request">
      <img src="https://user-images.githubusercontent.com/29775873/129506134-55044c85-24cd-47d3-81ef-dba842214d71.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/vuepress/vuepress-next">
      <img src="https://v2.vuepress.vuejs.org/images/hero.png" width="46"/>
    </a>
  </td>
  <td align="center" width="180">
    <a href="https://github.com/zoo-js/zoo">
      <img src="https://avatars1.githubusercontent.com/u/70757173?s=200&v=4" width="46"/>
    </a>
  </td>
</tr>
<tr>
  <td align="center" width="180"><a href="https://github.com/vitest-dev/vitest">vitest</a></td>
  <td align="center" width="180"><a href="https://github.com/AttoJS/vue-request">vue-request</a></td>
  <td align="center" width="180"><a href="https://github.com/vuepress/vuepress-next">vuepress-next</a></td>
  <td align="center" width="180"><a href="https://github.com/zoo-js/zoo">zoo</a></td>
</tr>
</table>

## 图标

如果觉得 actions-cool 能帮到你，欢迎复制到 README 中支持，推广给更多的项目：[![actions-cool](https://img.shields.io/badge/using-actions--cool-blue?style=flat-square)](https://github.com/actions-cool)，[更多样式](https://github.com/actions-cool/issues-helper/issues/92)。

```
[![actions-cool](https://img.shields.io/badge/using-actions--cool-blue?style=flat-square)](https://github.com/actions-cool)
```

## ⚡ 反馈

非常欢迎你来尝试使用，并提出意见，你可以通过以下方式：

- 通过 [Issue](https://github.com/actions-cool/issues-helper/issues) 报告 bug 或进行咨询
- 通过 [Discussions](https://github.com/actions-cool/issues-helper/discussions) 进行讨论
- 提交 [Pull Request](https://github.com/actions-cool/issues-helper/pulls) 改进 `issues-helper` 的代码

也欢迎加入 钉钉交流群

![](https://gw.alipayobjects.com/mdn/rms_f97235/afts/img/A*-iuDSpF7QAQAAAAAAAAAAAAAARQnAQ)

## 列 表

当以下列表没有你想要的功能时，可以在 [issues](https://github.com/actions-cool/issues-helper/issues) 中提出。

- ⭐ 基 础
  - [`add-assignees`](#add-assignees)
  - [`add-labels`](#add-labels)
  - [`close-issue`](#close-issue)
  - [`create-comment`](#create-comment)
  - [`create-issue`](#create-issue)
  - [`create-label`](#create-label)
  - [`delete-comment`](#delete-comment)
  - [`get-issue`](#get-issue)
  - [`lock-issue`](#lock-issue)
  - [`open-issue`](#open-issue)
  - [`remove-assignees`](#remove-assignees)
  - [`remove-labels`](#remove-labels)
  - [`set-labels`](#set-labels)
  - [`unlock-issue`](#unlock-issue)
  - [`update-comment`](#update-comment)
  - [`update-issue`](#update-issue)
- 🌟 进 阶
  - [`check-inactive`](#check-inactive)
  - [`check-issue`](#check-issue)
  - [`close-issues`](#close-issues)
  - [`find-comments`](#find-comments)
  - [`find-issues`](#find-issues)
  - [`lock-issues`](#lock-issues)
  - [`mark-assignees`](#mark-assignees)
  - [`mark-duplicate`](#mark-duplicate)
  - [`toggle-labels`](#toggle-labels)
  - [`welcome`](#welcome)

## 🚀 使 用

### ⭐ 基 础

<wrapper base data-depth="2" data-warn="DO_NOT_REMOVE_THIS_COMMENT">

为了更好的展示功能，下面以实际场景举例，请灵活参考。

#### `add-assignees`

当一个 issue 新增或修改时，将这个 issue 指定某人或多人。

```yml
name: Add Assigness

on:
  issues:
    types: [opened, edited]

jobs:
  add-assigness:
    runs-on: ubuntu-latest
    steps:
      - name: Add assigness
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'add-assignees'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
          assignees: 'xxx' or 'xx1,xx2'
          random-to: 1
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| assignees | 指定人。当不填或者为空字符时，不操作 | string | ✖ |
| random-to | 当设置时，会在 assignees 中随机选择 | number | ✖ |

- `actions` 支持多个，需用逗号隔开。如：`add-assignees, add-labels`
- 其中的 `name` 可根据自行根据实际情况修改
- [on 参考](#github-docs)
- `${{ github.event.issue.number }}` 表示当前 issue 编号，[更多参考](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events)
- `assignees` 支持多个，需用逗号隔开
- assign 最多只能设定 10 个

[⏫ 返回列表](#列-表)

#### `add-labels`

当一个新增的 issue 内容不包含指定格式时，为这个 issue 添加 labels。

```yml
name: Add Labels

on:
  issues:
    types: [opened]

jobs:
  add-labels:
    runs-on: ubuntu-latest
    if: contains(github.event.issue.body, 'xxx') == false
    steps:
      - name: Add labels
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'add-labels'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
          labels: 'bug' or 'bug1, bug2'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| labels | 新增的 labels。当不填或者为空字符时，不新增 | string | ✖ |

- `labels` 支持多个，需用逗号隔开

[⏫ 返回列表](#列-表)

#### `close-issue`

关闭指定 issue。

```yml
- name: Close issue
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'close-issue'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: xxx
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| close-reason | 关闭原因。默认`not_planned`未计划，`completed`完成 | string | ✖ |

[⏫ 返回列表](#列-表)

#### `create-comment`

当新增一个指定 label 时，对该 issue 进行评论。

```yml
name: Create Comment

on:
  issues:
    types: [labeled]

jobs:
  create-comment:
    runs-on: ubuntu-latest
    if: github.event.label.name == 'xxx'
    steps:
      - name: Create comment
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'create-comment'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
          body: |
            Hello ${{ github.event.issue.user.login }}. Add some comments.

            你好 ${{ github.event.issue.user.login }}。巴拉巴拉。
          emoji: '+1' or '+1,heart'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| body | 新增评论的内容  | string | ✔ |
| emoji | 为新增评论的增加 [emoji](#emoji-类型) | string | ✖ |

- `body` 为空时，无操作
- 返回 `comment-id`，可用于之后操作。[用法参考](#outputs-使用)
- `${{ github.event.issue.user.login }}` 表示该 issue 的创建者
- `emoji` 支持多个，需用逗号隔开

[⏫ 返回列表](#列-表)

#### `create-issue`

感觉新增 issue 使用场景不多。这里举例，每月 1 号 UTC 00:00 新增一个 issue。

```yml
name: Create Issue

on:
  schedule:
    - cron: "0 0 1 * *"

jobs:
  create-issue:
    runs-on: ubuntu-latest
    steps:
      - name: Create issue
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'create-issue'
          token: ${{ secrets.GITHUB_TOKEN }}
          title: 'xxxx'
          body: 'xxxx'
          labels: 'xx'
          assignees: 'xxx'
          emoji: '+1'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| title | 新增 issue 的标题 | string | ✔ |
| body | 新增 issue 的内容 | string | ✖ |
| labels | 为新增 issue 添加 labels | string | ✖ |
| assignees | 为新增 issue 添加 assignees | string | ✖ |
| random-to | 当设置时，会在 assignees 中随机选择 | number | ✖ |
| emoji | 为新增 issue 增加 [emoji](#emoji-types) | string | ✖ |

- `title` 为空时，无操作
- 返回 `issue-number`，[用法参考](#outputs-使用)

[⏫ 返回列表](#列-表)

#### `create-label`

新增 label。若想批量维护 labels，[可查看](https://github.com/actions-cool/labels-helper)。

```yml
- name: Create label
  uses: actions-cool/issues-helper@v3
  with:
    actions: 'create-label'
    token: ${{ secrets.GITHUB_TOKEN }}
    label-name: 'xx'
    label-color: '0095b3'
    label-desc: 'xx'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| label-name | 标签名称，支持 emoji | string | ✔ |
| label-color | 标签颜色，格式为 16 进制色码，不加 `#` | string | ✖ |
| label-desc | 标签描述 | string | ✖ |

- `label-name`：若已存在，则无操作
- `label-color`：默认为 `ededed`

[⏫ 返回列表](#列-表)

#### `delete-comment`

根据 [`comment-id`](#comment-id) 删除指定评论。

```yml
- name: Delete comment
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'delete-comment'
      token: ${{ secrets.GITHUB_TOKEN }}
      comment-id: xxx
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| comment-id | 指定的 comment | number | ✔ |

[⏫ 返回列表](#列-表)

#### `get-issue`

查询 issue 信息。

```yml
- name: Get Issue
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'get-issue'
      token: ${{ secrets.GITHUB_TOKEN }}
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |

- 返回 `issue-number` `issue-title` `issue-body` `issue-labels` `issue-assignees` `issue-state`，[用法参考](#outputs-使用)

[⏫ 返回列表](#列-表)

#### `lock-issue`

当新增 `invalid` label 时，对该 issue 进行锁定。

```yml
name: Lock Issue

on:
  issues:
    types: [labeled]

jobs:
  lock-issue:
    runs-on: ubuntu-latest
    if: github.event.label.name == 'invalid'
    steps:
      - name: Lock issue
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'lock-issue'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| lock-reason | 锁定 issue 的原因 | string | ✖ |

- `lock-reason`：可选值有 `off-topic` `too heated` `resolved` `spam`

[⏫ 返回列表](#列-表)

#### `open-issue`

打开指定 issue。

```yml
- name: Open issue
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'open-issue'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: xxx
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |

[⏫ 返回列表](#列-表)

#### `remove-assignees`

移除 issue 指定人员。

```yml
- name: Remove assignees
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'remove-assignees'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: ${{ github.event.issue.number }}
      assignees: 'xx'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| assignees | 移除的指定人。当为空字符时，不进行移除 | string | ✔ |

[⏫ 返回列表](#列-表)

#### `remove-labels`

移除指定 labels。

```yml
- name: Remove labels
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'remove-labels'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: ${{ github.event.issue.number }}
      labels: 'xx'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| labels | 移除的 labels。当为空字符时，不进行移除 | string | ✔ |

- `labels` 支持多个，如 `x1,x2,x3`，只会移除 issue 已添加的 labels

[⏫ 返回列表](#列-表)

#### `set-labels`

替换 issue 的 labels。

```yml
- name: Set labels
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'set-labels'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: ${{ github.event.issue.number }}
      labels: 'xx'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| labels | labels 设置。当空字符时，会移除所有 | string | ✔ |

[⏫ 返回列表](#列-表)

#### `unlock-issue`

解锁指定 issue。

```yml
- name: Unlock issue
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'unlock-issue'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: ${{ github.event.issue.number }}
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |

[⏫ 返回列表](#列-表)

#### `update-comment`

根据 [`comment-id`](#comment-id) 更新指定评论。

下面的例子展示的是，为每个新增的 comment 增加 👀 。

```yml
name: Add eyes to each comment

on:
  issue_comment:
    types: [created]

jobs:
  update-comment:
    runs-on: ubuntu-latest
    steps:
      - name: Update comment
          uses: actions-cool/issues-helper@v3
          with:
            actions: 'update-comment'
            token: ${{ secrets.GITHUB_TOKEN }}
            comment-id: ${{ github.event.comment.id }}
            emoji: 'eyes'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| comment-id | 指定的 comment | number | ✔ |
| body | 更新 comment 的内容 | string | ✖ |
| update-mode | 更新模式。默认 `replace` 替换，`append` 附加 | string | ✖ |
| emoji | 增加 [emoji](#emoji-types) | string | ✖ |

- `body` 不填时，会保持原有
- `update-mode` 为 `append` 时，会进行附加操作。非 `append` 都会进行替换。仅对 `body` 生效

[⏫ 返回列表](#列-表)

#### `update-issue`

根据 `issue-number` 更新指定 issue。

```yml
- name: Update issue
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'update-issue'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: ${{ github.event.issue.number }}
      state: 'open'
      title: 'xxx'
      body: 'xxxx'
      update-mode: 'replace'
      labels: 'xx'
      assignees: 'xxx'
      emoji: '+1'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| state | 修改 issue 的状态，可选值 `open` `closed` | string | ✖ |
| title | 修改 issue 的标题 | string | ✖ |
| body | 修改 issue 的内容 | string | ✖ |
| update-mode | 更新模式。默认 `replace` 替换，`append` 附加 | string | ✖ |
| labels | 替换 issue 的 labels | string | ✖ |
| assignees | 替换 issue 的 assignees | string | ✖ |
| emoji | 增加 [emoji](#emoji-types) | string | ✖ |

- `state` 默认为 `open`
- 当可选项不填时，会保持原有

[⏫ 返回列表](#列-表)
</wrapper>

### 🌟 进 阶
<wrapper advanced data-depth="2" data-warn="DO_NOT_REMOVE_THIS_COMMENT">

进阶用法不建议 actions 多个一次同时使用。

#### `check-inactive`

每月 1 号 UTC 0 时，对所有 30 天以上未活跃的 issues 增加 `inactive` 标签。

```yml
name: Check inactive

on:
  schedule:
    - cron: "0 0 1 * *"

jobs:
  check-inactive:
    runs-on: ubuntu-latest
    steps:
      - name: check-inactive
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'check-inactive'
          token: ${{ secrets.GITHUB_TOKEN }}
          inactive-day: 30
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| body | 操作 issue 时，可进行评论。不填时，不评论 | string | ✖ |
| emoji | 为该评论增加 [emoji](#emoji-types) | string | ✖ |
| labels | 标签筛选 | string | ✖ |
| issue-state | 状态筛选 | string | ✖ |
| issue-assignee | 指定人筛选 | string | ✖ |
| issue-creator | 创建人筛选 | string | ✖ |
| issue-mentioned | 提及人筛选 | string | ✖ |
| body-includes | 包含内容筛选 | string | ✖ |
| title-includes | 包含标题筛选 | string | ✖ |
| inactive-day | 非活跃天数筛选 | number | ✖ |
| inactive-mode | 检测不活跃的模式 | string | ✖ |
| inactive-label | 新增标签名称 | string | ✖ |
| exclude-labels | 排除标签筛选 | string | ✖ |

- `labels`：为多个时，会查询同时拥有多个。不填时，会查询所有
- `issue-state`：默认为 `open`。可选值 `all` `closed`，非这 2 项时，均为 `open`
- `issue-assignee`：不支持多人。不填或输入 * 时，查询所有。输入 `none` 会查询未添加指定人的 issues
- `inactive-day`：当输入时，会筛选 issue 更新时间早于当前时间减去非活跃天数。不填时，会查询所有
- `inactive-label`：默认为 `inactive`，可自定义其他。当项目未包含该 label 时，会自动新建
- `exclude-labels`：设置包含 `$exclude-empty` 时，可排除无 label issue
- `inactive-mode`:
  - 默认 `issue`，检查 issue 的更新时间
  - 可选 `comment`，检查最后一个评论的更新时间
  - 可选 `issue-created`，检查 issue 的创建时间
  - 可选 `comment-created`，最后一个评论的创建时间
  - 你也可以设置多个如：`comment, issue-created`
    - 将会以优先级检测，先检测最后一条评论更新时间，如无评论，则使用 issue 的创建时间

[⏫ 返回列表](#列-表)

#### `check-issue`

根据传入的参数和 `issue-number` 来检查该 issue 是否满足条件，返回一个布尔值。

下面的例子效果是：当 issue 新开时，校验当前 issue 指定人是否包含 `x1` 或者 `x2`，满足一个指定人即可校验通过，同时校验标题是否满足条件，[校验规则](#校验规则)。

```yml
name: Check Issue

on:
  issues:
    types: [edited]

jobs:
  check-issue:
    runs-on: ubuntu-latest
    steps:
      - name: check-issue
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'check-issue'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
          assignee-includes: 'x1,x2'
          title-includes: 'x1,x2/y1,y2'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| assignee-includes | 是否包含指定人 | string | ✖ |
| title-includes | 标题包含校验 | string | ✖ |
| title-excludes | 检测标题移除默认 title 后是否为空 | string | ✖ |
| body-includes | 内容包含校验 | string | ✖ |

- `title-includes` `body-includes` 支持格式 `x1,x2` 或者 `x1,x2/y1,y2`。只支持两个层级
- 返回 `check-result`，由于 yml 原因，判断条件为 `if: steps.xxid.outputs.check-result == 'true'`

[⏫ 返回列表](#列-表)

#### `close-issues`

每 7 天 UTC 0 时，关闭已填加 `need info` label 且 7 天以上未活跃的 issues。

```yml
name: Check need info

on:
  schedule:
    - cron: "0 0 */7 * *"

jobs:
  check-need-info:
    runs-on: ubuntu-latest
    steps:
      - name: close-issues
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'close-issues'
          token: ${{ secrets.GITHUB_TOKEN }}
          labels: 'need info'
          inactive-day: 7
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| body | 操作 issue 时，可进行评论。不填时，不评论 | string | ✖ |
| emoji | 为该评论增加 [emoji](#emoji-types) | string | ✖ |
| labels | 标签筛选 | string | ✖ |
| issue-assignee | 指定人筛选 | string | ✖ |
| issue-creator | 创建人筛选 | string | ✖ |
| issue-mentioned | 提及人筛选 | string | ✖ |
| body-includes | 包含内容筛选 | string | ✖ |
| title-includes | 包含标题筛选 | string | ✖ |
| inactive-day | 非活跃天数筛选 | number | ✖ |
| exclude-labels | 排除标签筛选 | string | ✖ |
| close-reason | 关闭原因。默认`not_planned`未计划，`completed`完成 | string | ✖ |

- `labels`：为多个时，会查询同时拥有多个。不填时，会查询所有
- `issue-assignee`：不支持多人。不填或输入 * 时，查询所有。输入 `none` 会查询未添加指定人的 issues
- `inactive-day`：当输入时，会筛选 issue 更新时间早于当前时间减去非活跃天数。不填时，会查询所有
- `exclude-labels`：设置包含 `$exclude-empty` 时，可排除无 label issue

[⏫ 返回列表](#列-表)

#### `find-comments`

查找当前仓库 1 号 issue 中，创建者是 k ，内容包含 `this` 的评论列表。

```yml
- name: Find comments
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'find-comments'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-number: 1
      comment-auth: 'k'
      body-includes: 'this'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| comment-auth | 评论创建者，不填时会查询所有 | string | ✖ |
| body-includes | 评论内容包含过滤，不填时无校验 | string | ✖ |
| direction | 返回 `comments` 排序 | string | ✖ |

- 返回 `comments`，格式如下：

```js
[
  {id: 1, auth: 'x', body: 'xxx', created: '', updated: ''},
  {id: 2, auth: 'x', body: 'xxx', created: '', updated: ''},
]
```

- `direction` 默认为升序，只有设置 `desc` 时，会返回降序
- 返回数组中 `created` `updated`，由所处环境决定，会是 UTC +0

[⏫ 返回列表](#列-表)

#### `find-issues`

查找当前仓库，创建者是 k ，title 包含 `this` ，body 包含 `that`，打开状态的 issues 列表。

```yml
- name: Find issues
    uses: actions-cool/issues-helper@v3
    with:
      actions: 'find-issues'
      token: ${{ secrets.GITHUB_TOKEN }}
      issue-creator: 'k'
      issue-state: 'open'
      title-includes: 'this'
      body-includes: 'that'
      labels: 'documentation'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-state | 状态筛选 | string | ✖ |
| issue-creator | 创建者筛选 | string | ✖ |
| title-includes | 标题包含过滤，不填时无校验 | string | ✖ |
| body-includes | 内容包含过滤，不填时无校验 | string | ✖ |
| labels | 标签筛选 | string | ✖ |
| exclude-labels | 排除标签筛选 | string | ✖ |
| inactive-day | 非活跃天数筛选 | number | ✖ |
| direction | 返回 `issues` 排序 | string | ✖ |

- 返回 `issues`，格式如下：

```js
[
  {number: 1, auth: 'x', body: 'xxx', body: 'xxx', state: 'open', assignees: ['x1', 'x2'], created: '', updated: ''},
  {number: 2, auth: 'x', body: 'xxx', body: 'xxx', state: 'closed', assignees: ['x1', 'x2'], created: '', updated: ''},
]
```

- `direction` 默认为升序，只有设置 `desc` 时，会返回降序
- 返回数组中 `created` `updated`，由所处环境决定，会是 UTC +0
- `exclude-labels`：设置包含 `$exclude-empty` 时，可排除无 label issue

[⏫ 返回列表](#列-表)

#### `lock-issues`

每 3 个月 1 号 UTC 0 时，锁定已填加 `inactive` label 且 128 天以上未活跃的所有 issues。

```yml
name: Lock inactive issues

on:
  schedule:
    - cron: "0 0 1 */3 *"

jobs:
  lock-issues:
    runs-on: ubuntu-latest
    steps:
      - name: lock-issues
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'lock-issues'
          token: ${{ secrets.GITHUB_TOKEN }}
          labels: 'inactive'
          inactive-day: 128
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| body | 操作 issue 时，可进行评论。不填时，不评论 | string | ✖ |
| emoji | 为该评论增加 [emoji](#emoji-types) | string | ✖ |
| labels | 标签筛选 | string | ✖ |
| issue-state | 状态筛选 | string | ✖ |
| issue-assignee | 指定人筛选 | string | ✖ |
| issue-creator | 创建人筛选 | string | ✖ |
| issue-mentioned | 提及人筛选 | string | ✖ |
| body-includes | 包含内容筛选 | string | ✖ |
| title-includes | 包含标题筛选 | string | ✖ |
| inactive-day | 非活跃天数筛选 | number | ✖ |
| lock-reason | 锁定 issue 的原因 | string | ✖ |
| exclude-labels | 排除标签筛选 | string | ✖ |

- `labels`：为多个时，会查询同时拥有多个。不填时，会查询所有
- `issue-state`：默认为 `open`。可选值 `all` `closed`，非这 2 项时，均为 `open`
- `issue-assignee`：不支持多人。不填或输入 * 时，查询所有。输入 `none` 会查询未添加指定人的 issues
- `inactive-day`：当输入时，会筛选 issue 更新时间早于当前时间减去非活跃天数。不填时，会查询所有
- `exclude-labels`：设置包含 `$exclude-empty` 时，可排除无 label issue

[⏫ 返回列表](#列-表)

#### `mark-assignees`

快捷加指定人，仅作用于 issue 新增编辑评论。

```yml
name: Issue Mark Assignees

on:
  issue_comment:
    types: [created, edited]

jobs:
  mark-assignees:
    runs-on: ubuntu-latest
    steps:
      - name: mark-assignees
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'mark-assignees'
          token: ${{ secrets.GITHUB_TOKEN }}
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| assign-command | 可设置简洁命令，如：`/a` | string | ✖ |
| require-permission | 要求权限，默认为 `write` | string | ✖ |

- `assign-command`：可设置简洁命令。默认：`/assign`
- `require-permission`：可选值有 `admin`，`write`，`read`，`none`
  - 团队成员若设置 `read` 权限，则为 `read`
  - 外部 Collaborator 若设置 `read` 权限，则为 `read`
  - 普通用户为 `read` 权限
  - 当设置 `write` 后，`admin` 和 `write` 满足条件

[⏫ 返回列表](#列-表)

#### `mark-duplicate`

快捷标记重复问题，仅作用于 issue 新增编辑评论。

```yml
name: Issue Mark Duplicate

on:
  issue_comment:
    types: [created, edited]

jobs:
  mark-duplicate:
    runs-on: ubuntu-latest
    steps:
      - name: mark-duplicate
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'mark-duplicate'
          token: ${{ secrets.GITHUB_TOKEN }}
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| duplicate-command | 可设置简洁命令，如：`/d` | string | ✖ |
| duplicate-labels | 为该 issue 额外增加 labels | string | ✖ |
| remove-labels | 设置可移除的 labels | string | ✖ |
| labels | 替换该 issue 的 labels | string | ✖ |
| emoji | 为该评论的增加 [emoji](#emoji-types) | string | ✖ |
| close-issue | 是否同时关闭该 issue | string | ✖ |
| require-permission | 要求权限，默认为 `write` | string | ✖ |
| close-reason | 关闭原因。默认`not_planned`未计划，`completed`完成 | string | ✖ |

- `duplicate-command`：当设置简洁命令时，同时仍支持原有 `Duplicate of`。屏蔽内容包含 `?`
- `labels`：优先级最高
- `close-issue`：`true` 或 `'true'` 均可生效
- `require-permission`：可选值有 `admin`，`write`，`read`，`none`
  - 团队成员若设置 `read` 权限，则为 `read`
  - 外部 Collaborator 若设置 `read` 权限，则为 `read`
  - 普通用户为 `read` 权限
  - 当设置 `write` 后，`admin` 和 `write` 满足条件

[⏫ 返回列表](#列-表)

#### `toggle-labels`

当一个 issue 被重新打开，判断设置的 labels 如果已经存在则进行删除，否则进行添加。

```yml
name: Toggle Labels

on:
  issues:
    types: [reopened]

jobs:
  toggle-labels:
    runs-on: ubuntu-latest
    steps:
      - name: Toggle labels
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'toggle-labels'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
          labels: 'unread,outdated'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| issue-number | 指定的 issue，当不传时会从触发事件中获取 | number | ✖ |
| labels | 切换 labels。如果 label 已存在则删除，不存在则添加 | string | ✖ |

[⏫ 返回列表](#列-表)

#### `welcome`

当一个 issue 新建时，对首次新建 issue 的用户进行欢迎。若用户非首次新建，则无操作。

```yml
name: Issue Welcome

on:
  issues:
    types: [opened]

jobs:
  issue-welcome:
    runs-on: ubuntu-latest
    steps:
      - name: welcome
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'welcome'
          token: ${{ secrets.GITHUB_TOKEN }}
          body: hi @${{ github.event.issue.user.login }}, welcome!
          labels: 'welcome1, welcome2'
          assignees: 'xx1'
          issue-emoji: '+1, -1, eyes'
```

| 参数 | 描述 | 类型 | 必填 |
| -- | -- | -- | -- |
| actions | 操作类型 | string | ✔ |
| token | [token 说明](#token) | string | ✖ |
| body | 评论欢迎的内容，不填则不评论 | string | ✖ |
| emoji | 为该评论的增加 [emoji](#emoji-types) | string | ✖ |
| labels | 为该 issue 增加 labels | string | ✖ |
| assignees | 为该 issue 增加 assignees | string | ✖ |
| issue-emoji | 为该 issue 增加 [emoji](#emoji-types) | string | ✖ |

- 若这 4 个可选项都不填，则无操作

[⏫ 返回列表](#列-表)
</wrapper>

## 🎁 参 考
<wrapper reference data-depth="1" data-warn="DO_NOT_REMOVE_THIS_COMMENT">

### token

需拥有 push 权限的人员 token。

- [个人 token 申请](https://github.com/settings/tokens)
  - 需勾选 `Full control of private repositories`
- 项目添加 secrets
  - 选择 settings，选择 secrets，选择 `New repository secret`
  - `Name` 与 actions 中保持一致
  - `Value` 填写刚才个人申请的 token

当 actions 不填写 token 时，或填写 `${{ secrets.GITHUB_TOKEN }}`，会默认为 `github-actions-bot`。[更多查看](https://docs.github.com/en/actions/security-guides/automatic-token-authentication)。

[⏫ 返回列表](#列-表)

### GitHub Docs

- [GitHub Actions 语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows)
- [工作流触发机制](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)

[⏫ 返回列表](#列-表)

### `outputs` 使用

```yml
- name: Create issue
  uses: actions-cool/issues-helper@v3
  id: createissue
  with:
    actions: 'create-issue'
    token: ${{ secrets.GITHUB_TOKEN }}
- name: Check outputs
  run: echo "Outputs issue_number is ${{ steps.createissue.outputs.issue-number }}"
```

更多查看：

1. https://docs.github.com/en/free-pro-team@latest/actions/creating-actions/metadata-syntax-for-github-actions#outputs
2. https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idoutputs

[⏫ 返回列表](#列-表)

### 校验规则

```js
"title-includes": 'x1,x2'

x1
x2

"x1y3y2"  true
"y2 x1"   true
"x2"      true
"x3"      false
```

```js
"title-includes": 'x1,x2/y1,y2'

x1 + y1
x2 + y1
x1 + y2
x2 + y2

"x1y3y2"  true
"y2 x1"   true
"1x2y"    false
"x1"      false
```

[⏫ 返回列表](#列-表)

### emoji 类型

| content | emoji |
| -- | -- |
| `+1` | 👍 |
| `-1` | 👎 |
| `laugh` | 😄 |
| `confused` | 😕 |
| `heart` | ❤️ |
| `hooray` | 🎉 |
| `rocket` | 🚀 |
| `eyes` | 👀 |

[⏫ 返回列表](#列-表)

### `comment-id`

点击某个评论右上角 `···` 图标，选择 `Copy link`，url 末尾数字即是 `comment_id`。

[⏫ 返回列表](#列-表)
</wrapper>

## Actions 模板

- 可直接使用这个 [GitHub Actions workflow template](https://github.com/actions-cool/.github) 仓库的模板
- 个人练习和测试 [Actions](https://github.com/actions-cool/test-issues-helper) 的仓库
- 也可以来 [线上使用者](#谁在使用) 的仓库参照

## LICENSE

[MIT](https://github.com/actions-cool/issues-helper/blob/main/LICENSE)