action-gh-release

<div align="center"> 📦 :octocat: </div> <h1 align="center"> action gh-release </h1> <p align="center"> 一个用于在 Linux、Windows 和 macOS 虚拟环境中创建 GitHub Releases 的 GitHub Action </p> <div align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/ba5d0489-7a68-46ef-a13a-60f588383950.png"/> </div> <div align="center"> <a href="https://github.com/softprops/action-gh-release/actions"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/8a78bcc6-c0b7-4547-bfbb-387f73b3b54a.svg"/> </a> </div> <br />

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

🤸 使用方法

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

通常，这个 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	字符串	加载传达本次发布重要变更文本的路径
draft	布尔值	指示该发布是否为草稿
prerelease	布尔值	指示是否为预发布
files	字符串	用于上传发布资产的路径的换行分隔glob
name	字符串	发布名称，默认为标签名
tag_name	字符串	标签名，默认为github.ref
fail_on_unmatched_files	布尔值	指示如果任何files glob没有匹配项是否失败
repository	字符串	目标仓库名称，格式为<所有者>/<仓库>。默认为GITHUB_REPOSITORY环境变量
target_commitish	字符串	决定从哪里创建Git标签的提交值。可以是任何分支或提交SHA。默认为仓库默认分支。
token	字符串	秘密GitHub个人访问令牌。默认为${{ github.token }}
discussion_category_name	字符串	如果指定，将创建指定类别的讨论并链接到发布。该值必须是仓库中已存在的类别。有关更多信息，请参阅"管理仓库中的讨论类别"
generate_release_notes	布尔值	是否自动生成此发布的名称和正文。如果指定了名称，将使用指定的名称；否则，将自动生成名称。如果指定了正文，该正文将被添加到自动生成的注释之前。有关此功能的更多信息，请参阅GitHub文档
append_body	布尔值	追加到现有正文而不是覆盖它
make_latest	字符串	指定此发布是否应设置为仓库的最新发布。草稿和预发布不能设置为最新。可以是true、false或legacy。如果未提供，则使用GitHub API默认值

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

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

输出

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

名称	类型	描述
url	字符串	发布的Github.com URL
id	字符串	发布ID
upload_url	字符串	用于上传资产到发布的URL
assets	字符串	包含每个上传资产信息的JSON数组，格式如此处所示（不包括uploader字段）

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

环境变量

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

名称	描述
GITHUB_TOKEN	由secrets提供的GITHUB_TOKEN
GITHUB_REPOSITORY	目标仓库名称，格式为<所有者>/<仓库>。默认为当前仓库

⚠️ 注意： 此操作之前是作为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