jimschubert/labeler-action

labeler-action

概述

labeler-action 是一个GitHub Action，可基于issues和pull requests（PR）标题或描述中的正则表达式模式自动应用标签。v2及以上版本支持通过https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request_target%E4%BA%8B%E4%BB%B6%E4%B8%BAforked%E4%BB%93%E5%BA%93%E7%9A%84PR%E6%B7%BB%E5%8A%A0%E6%A0%87%E7%AD%BE%EF%BC%8C%E8%A7%A3%E5%86%B3%E4%BA%86%E4%BC%A0%E7%BB%9Fpull_request%E4%BA%8B%E4%BB%B6%E6%97%A0%E6%B3%95%E8%AE%BF%E9%97%AE%E5%9F%BA%E7%A1%80%E4%BB%93%E5%BA%93%E5%AF%86%E9%92%A5%E7%9A%84%E9%99%90%E5%88%B6%E3%80%82

核心功能与特性

• 双模式配置：支持简单模式（适用于基础场景）和完整模式（提供更精细的控制）
• 灵活的标签规则：可定义标签的包含（include）和排除（exclude）模式，基于正则表达式匹配内容
• 差异化配置：可针对issues和PR分别启用/禁用标签功能及自定义评论内容
• 分支限制：支持按PR目标分支限制标签应用范围
• 自动化评论：可为issues和PR自动添加标签操作相关的评论

使用场景

适用于需要自动化标签管理的GitHub仓库，特别是社区贡献活跃、需要根据内容自动分类issues和PR的项目。例如：

• 开源项目根据issue描述中的"bug"关键词自动添加"bug"标签
• 团队协作中根据PR标题中的"enhancement"自动标记"enhancement"标签
• 大型项目中通过标签自动区分不同类型的贡献，简化项目管理流程

使用方法

定义配置文件 .github/labeler.yml

该Action需要在仓库中创建配置文件 .github/labeler.yml，支持简单模式和完整模式两种配置方式。配置文件必须存在于发布分支（如master、main等）。

简单模式

适用于基础场景，为issues和PR应用相同的评论和标签规则：

yaml
# labeler "简单" 模式
# 评论同时应用于issues和PR
# 如需更复杂的配置，请考虑使用"完整"模式
comment: |
  👍 感谢提交！
  🏷 我已根据您的issue中特殊文本应用了匹配的标签。

  请检查标签并进行必要的调整。

# 标签配置：
# - 键为标签名称
# - 值为字符串模式数组，用于匹配issues/PR的标题+正文
labels:
  'bug':
    - '\bbug[s]?\b'  # 匹配"bug"或"bugs"
  'help wanted':
    - '\bhelp( wanted)?\b'  # 匹配"help"或"help wanted"
  'duplicate':
    - '\bduplicate\b'  # 匹配"duplicate"
    - '\bdupe\b'  # 匹配"dupe"
  'enhancement':
    - '\benhancement\b'  # 匹配"enhancement"
  'question':
    - '\bquestion\b'  # 匹配"question"

完整模式

提供更精细的控制，支持分别配置issues和PR的启用状态、评论内容及标签规则：

yaml
# labeler "完整" 模式

# 启用标签功能的对象（issues、PR或两者）
enable:
  issues: true  # 启用issues标签
  prs: true     # 启用PR标签

# 评论配置，可针对issues和PR设置不同内容
comments:
  issues: |
    感谢提交issue！
    我已根据标题和描述中的特殊文本应用了匹配的标签。

    请检查标签并进行必要的调整。
  prs: |
    感谢您的贡献！
    我已根据标题和描述中的特殊文本应用了匹配的标签。

    请检查标签并进行必要的调整。

# 标签配置：
# - 键为标签名称
# - 值为包含以下字段的对象：
#   - include: 匹配模式数组（任意模式匹配则应用标签）
#   - exclude: 排除模式数组（任意模式匹配则忽略标签）
#   - branches: 可选分支数组（仅当PR目标分支匹配时应用标签）
#   所有模式均为正则表达式，全局应用于标题+正文
labels:
  'bug':
    include:
      - '\bbug[s]?\b'  # 匹配"bug"或"bugs"
    exclude: []
    branches:
      - 'master'       # 仅应用于目标分支为master的PR
      - 'main'         # 仅应用于目标分支为main的PR
  'help wanted':
    include:
      - '\bhelp( me)?\b'  # 匹配"help"或"help me"
    exclude:
      - '\b\[test(ing)?\]\b'  # 排除包含"[test]"或"[testing]"的内容
  'enhancement':
    include:
      - '\bfeat\b'  # 匹配"feat"
    exclude: []

创建工作流文件

需创建工作流定义文件（如 .github/workflows/community.yml），配置触发事件和Action执行步骤。

工作流配置示例

yaml
name: 社区标签管理
on: 
  issues:
    types: [opened, edited, milestoned]  # 触发issues标签的事件类型
  pull_request_target:
    types: [opened]  # 触发PR标签的事件类型（使用pull_request_target支持forks）

jobs:
  labeler:
    runs-on: ubuntu-latest
    steps:
    - name: 应用标签
      id: labeler
      uses: jimschubert/labeler-action@v2  # 使用v2及以上版本
      with:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # 工作流默认提供的令牌，具有API访问权限

关键配置说明

• 触发事件：issues建议使用opened、edited事件；PR必须使用pull_request_target而非pull_request，以支持从forked仓库发起的PR（pull_request在fork场景下无法访问基础仓库密钥）。
• GITHUB_TOKEN：无需额外配置，工作流自动提供，具有操作仓库标签的权限。如需限制权限，可创建具有public_repo作用域的个人访问令牌并存储为secret。
• 版本选择：建议使用@v2或具体版本号（如@v2.1.0），避免直接使用@main分支。

许可证

本项目采用Apache 2.0许可证。