action gh-release

一个用于在 Linux、Windows 和 macOS 虚拟环境中创建 GitHub Releases 的 GitHub Action

• 🤸 使用方法
  • 🚥 限制仅在推送标签时创建发布
  • ⬆️ 上传发布资产
  • 📝 外部发布说明
  • 💅 自定义
    • 输入参数
    • 输出参数
    • 环境变量
  • 权限

🤸 使用方法

🚥 限制仅在推送标签时创建发布

通常，这个 Action 的使用涉及在构建中添加一个步骤，该步骤仅在推送 git 标签时触发。你可能会发现 step.if 字段在实现这一点时很有帮助，因为它可以最大化你的工作流程在非标签推送时的复用价值。

下面是一个使用 step.if 进行标签限制的简单示例

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 创建发布
        uses: softprops/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')

你也可以使用推送配置标签过滤器

name: Main

on:
  push:
    tags:
      - "v*.*.*"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 创建发布
        uses: softprops/action-gh-release@v2

⬆️ 上传发布资产

你可以为 GitHub 发布配置多个选项，所有选项都是可选的。

GitHub 发布的一个常见用例是在二进制文件经过验证和打包后上传。使用 with.files 输入来声明一个用换行符分隔的 glob 表达式列表，匹配你希望上传到 GitHub 发布的文件。如果你愿意，也可以直接列出文件名。如果标签已经有一个 GitHub 发布，现有的发布将会使用这些发布资产进行更新。

下面是上传单个名为 Release.txt 的资产的示例

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 构建
        run: echo ${{ github.sha }} > Release.txt
      - name: 测试
        run: cat Release.txt
      - name: 创建发布
        uses: softprops/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: Release.txt

下面是上传多个资产到 GitHub 发布的示例

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 构建
        run: echo ${{ github.sha }} > Release.txt
      - name: 测试
        run: cat Release.txt
      - name: 创建发布
        uses: softprops/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: |
            Release.txt
            LICENSE

⚠️ 注意： 请注意上面 yaml 语法中的 | ☝️。它允许你有效地声明多行 yaml 字符串。你可以在这里了解更多关于多行 yaml 语法的信息。

⚠️ Windows 注意事项： 路径必须使用 / 作为分隔符，而不是 \，因为 \ 用于转义具有特殊含义的字符；例如，不要指定 D:\Foo.txt，而应指定 D:/Foo.txt。如果你使用的是 PowerShell，可以这样做：$Path = $Path -replace '\\','/'

📝 外部发布说明

有许多系统可以帮助你生成发布说明。这个 Action 支持从你仓库构建中的路径加载发布说明，以便灵活使用任何更新日志生成器进行发布，包括人工编写 👩‍💻

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
      - name: 生成更新日志
        run: echo "# 好事即将到来" > ${{ github.workspace }}-CHANGELOG.txt
      - name: 创建发布
        uses: softprops/action-gh-release@v2
        if: startsWith(github.ref, 'refs/tags/')
        with:
          body_path: ${{ github.workspace }}-CHANGELOG.txt
          repository: my_gh_org/my_gh_repo
          # 注意，你通常需要创建一个具有在其他仓库中创建发布权限的个人访问令牌
          token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

💅 自定义

输入参数

以下是可选的 step.with 键

💡 同时提供body和body_path时，将首先尝试body_path，如果无法读取路径，则回退到body。

💡 当未明确设置发布信息键（如name、body、draft、prerelease等）且标签已存在发布时，该发布将保留其原始信息。

输出

可以通过${{ steps.<step-id>.outputs }}从此操作访问以下输出

例如，您可以使用${{ fromJSON(steps.<step-id>.outputs.assets)[0].browser_download_url }}获取第一个资产的下载URL。

环境变量

以下step.env键作为备用方案允许使用，但不推荐使用，推荐使用输入。

⚠️ 注意： 此操作之前是作为Docker容器实现的，仅限于GitHub Actions Linux虚拟环境使用。在最新版本中，我们现在支持跨平台使用。您需要在这些版本中删除docker://前缀

权限

此操作需要GitHub集成令牌具有以下权限：

permissions:
  contents: write

当与discussion_category_name一起使用时，需要额外的权限：

permissions:
  contents: write
  discussions: write

GitHub令牌权限可以为单个作业、工作流或整个Actions设置。

请注意，如果您打算在发布事件上运行工作流（on: { release: { types: [published] } }），您需要为此操作使用个人访问令牌，因为默认的secrets.GITHUB_TOKEN不会触发另一个工作流。

Doug Tangren (softprops) 2019