tiangolo/latest-changes Docker镜像文档

镜像概述和主要用途

tiangolo/latest-changes 是一个GitHub Action Docker镜像，旨在自动将每个Pull Request (PR) 的更改信息添加到项目的发布说明文件中。通过配置工作流，在PR合并到主分支后，该镜像可自动在指定文件的特定位置插入PR标题、链接及作者信息，减少手动维护版本更新文档的工作量。

核心功能和特性

• 自动更新发布说明：合并PR到主分支后，自动在指定文件的特定标题下添加PR相关信息
• 自定义配置：支持指定目标文件、标题格式、Jinja2模板等
• 手动触发：支持通过工作流手动触发，处理添加该Action前已存在的PR
• 调试日志：可开启调试模式，显示当前配置信息便于问题排查
• 兼容保护分支：通过配置个人访问令牌，支持向受保护分支推送更新

使用场景和适用范围

适用于使用GitHub进行版本控制的项目，尤其是需要频繁更新发布说明、变更日志的场景。无论是小型个人项目还是大型团队协作项目，均可通过该Action简化版本更新文档的维护流程。

使用方法和配置说明

基本使用示例

1. 在项目中创建工作流文件：.github/workflows/latest-changes.yml
2. 添加以下最小配置示例：

yaml
name: Latest Changes

on:
  pull_request_target:
    branches:
      - main  # 或使用你的主分支名称，如master
    types:
      - closed
  workflow_dispatch:  # 支持手动触发
    inputs:
      number:
        description: PR编号
        required: true

jobs:
  latest-changes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: docker://tiangolo/latest-changes:0.0.3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

注意事项

• 也可直接使用GitHub Action（非Docker方式），但执行速度较慢：

  yaml
  # - uses: docker://tiangolo/latest-changes:0.0.3  # Docker方式（较快）
  - uses: tiangolo/latest-changes:0.0.3  # 直接使用Action（较慢但同样有效）
  

• 默认行为说明：

  • 目标文件为项目根目录的README.md
  • 在文件中查找标题：### Latest Changes\n\n（包含两个换行符）
  • 在该标题后添加列表项，内容包括PR标题、PR链接及作者链接

手动触发现有PR

对于在添加此Action前已创建的PR，可通过以下步骤手动触发：

1. 进入GitHub仓库的"Actions"标签页
2. 选择名称为"Latest Changes"的工作流
3. 点击"Run Workflow"，输入PR编号并触发执行

配置参数

配置示例

完整配置示例

以下是使用所有配置参数的示例，包括自定义Jinja2模板：

1. 创建Jinja2模板文件：.github/workflows/release-notes.jinja2，内容如下：

   jinja2
   变更内容：{{pr.title}}。由 GitHub用户 {{pr.user.login}} 完成。查看 PR {{pr.number}} 详情。返回代码开发。🤓\n\n
   

   说明：模板需以两个换行符结尾，确保下一条记录正确换行；pr对象为PyGitHub PullRequest对象，可提取更多信息。

2. 工作流配置文件：

   yaml
   name: Latest Changes
   
   on:
     pull_request_target:
       branches:
         - master  # 使用master作为主分支
       types:
         - closed
     workflow_dispatch:
       inputs:
         number:
           description: PR编号
           required: true
   
   jobs:
     latest-changes:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - uses: tiangolo/latest-changes:0.0.3
           with:
             token: ${{ secrets.GITHUB_TOKEN }}
             latest_changes_file: docs/release-notes.md  # 自定义目标文件
             latest_changes_header: '# Release Notes\n\n'  # 自定义标题
             template_file: ./.github/workflows/release-notes.jinja2  # 自定义模板
             debug_logs: true  # 开启调试日志
   

保护分支配置

若主分支（如main或master）为受保护分支，需通过以下步骤配置以允许Action推送更改：

1. 创建个人访问令牌，授予repo权限
2. 在仓库"Settings" → "Secrets"中添加新密钥，名称设为ACTIONS_TOKEN，值为上述访问令牌
3. 修改工作流配置，将令牌传递给actions/checkout@v2：

yaml
name: Latest Changes

on:
  pull_request_target:
    branches:
      - main
    types:
      - closed
  workflow_dispatch:
    inputs:
      number:
        description: PR编号
        required: true

jobs:
  latest-changes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          token: ${{ secrets.ACTIONS_TOKEN }}  # 使用自定义令牌
      - uses: docker://tiangolo/latest-changes:0.0.3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

说明：自定义令牌仅用于推送更改，提交仍会显示为github-actions用户（用户名：github-actions，***：***）。