发表更新devops20 分钟读完 (大约3012个字)0次访问

教程：使用GitLab自动发布程序并生成发布说明

翻译：RangWu
原文：《Tutorial: Automate releases and release notes with GitLab — Ben Ridley》

img

在开发软件时，对每次发布的变更进行有效沟通至关重要。将新功能以及任何修改或删除及时通知用户，确保他们能正确使用软件，并在升级过程中避免一些意外。

以往创建发布说明和维护变更日志是一项繁重的任务，需要开发人员密切关注外部变更或由专门负责发布的经理筛选合并历史。而使用GitLab的Changelog API，您可以通过git仓库中提供的丰富的历史信息轻松创建发布说明和维护变更日志。

在本文中，我们将深入探讨如何使用GitLab自动化发布程序，包括生成发布制品、发布说明和详细的面向用户的软件变更日志。

GitLab的发布

首先，让我们了解GitLab中的发布（Release）是如何工作的。

在GitLab中，发布是代码的一个特定版本，由git标签（Tag）来标识，其中包括自上次发布以来的变更详情（与发布说明），以及从该代码版本构建的相关制品，例如Docker镜像、安装包和文档。

您可以使用UI在GitLab中创建和跟踪发布，也可以通过调用GitLab的Release API或在CI流水线中定义一个特殊的release任务来创建和跟踪发布。在本教程中，我们将在CI/CD流水线中创建release任务，这使得我们可以扩展流水线的自动化能力，在实现自动编译、测试、代码扫描的基础上，实现自动发布。

要实现自动化发布，我们首先需要回答一个问题：我们将从何处获取发布说明和变更日志的信息？答案是：git仓库，它为我们提供了通过提交消息（Commit Message）和合并提交（Merge Commit Message）的开发活动历史记录。让我们看看是否可以利用这些丰富的历史记录来自动创建发布说明和变更日志。

提交追踪器

Commit trailers 提交追踪器是git提交信息中的结构化条目，是通过将简单的<HEADER>:<BODY>格式消息添加到提交信息的末尾来创建的。git CLI工具可以解析并提取这些信息供其他系统使用。您可能已经使用过的一个示例是git commit --sign-off，它用于对提交进行签名。这是通过将Signed-off-by: <Your Name>追踪器添加到提交中来实现的。我们可以在这里添加任意的结构化数据，这使得它成为存储变更日志信息的好地方。

实际上，如果我们在提交中使用一个Changelog: <added/changed/removed>追踪器，GitLab Changelog API将解析这些信息并自动使用它们来为我们创建变更日志！

让我们通过对真实代码库进行一些修改，实现自动发布以及生成发布说明和变更日志条目，来看看它的效果。

示例项目

为了演示效果，这里使用了一个简单的Python web应用程序代码库。让我们模拟应用程序的1.0.0版本刚刚发布，并且是基于当前代码的版本。我还手动创建了一个1.0.0版本的GitLab发布，因为我们还没有创建自动发布流水线：

GitLab UI显示版本1.0.0的发布的屏幕截图

进行更改

假设我们正处于快速开发模式，今天我们将发布应用程序的2.0.0版本。作为2.0.0版本的一部分，我们将向应用程序中添加新功能：一个聊天机器人！并且我们将删除“量子区块链Quantum Blockchain功能”，因为我们只需要在首次风险投资中使用它。此外，我们将为2.0.0版本的CI/CD流水线添加一个自动发布任务。

首先，让我们删除不需要的功能。我创建了一个包含必要删除的合并请求。重要的是，我们需要确保提交消息包括Changelog: removed追踪器。有几种方法可以做到这一点，比如直接在提交信息（Commit Message）中包括它，或者使用git CLI通过交互式变基（rebase）来添加它。但在这个例子中，我使用了最简单的方法就是等到功能开发完，在合并请求中使用编辑提交消息按钮将追踪器添加到合并提交中，如下所示：

GitLab UI中显示包含未使用功能的合并请求的屏幕截图

如果使用此方法，您还可以更改合并提交标题，使其更为简洁。我已将我的合并提交的标题更改为“Remove unused features”，因为这将出现在变更日志条目中。

接下来，让我们为2.0.0版本添加一些新功能。同样，我们只需创建另一个包含新功能的合并请求，然后编辑合并提交以包括Changelog: added追踪器，并编辑提交标题“Add ChatBot”：

GitLab UI显示添加新功能的合并请求的屏幕截图

现在我们准备好可以发布2.0.0版本了。但这次我们不想手动创建发布。在发布之前，我们将向.gitlab-ci.yml文件添加一些任务，实现在代码上标记新版本，例如2.0.0时，自动执行发布，并生成相应的发布说明和变更日志条目。

注意：如果要强制设置变更追踪器，请考虑使用类似于dangerbot的工具来执行有关MR规范的自动检查。

构建自动发布流水线

为了使流水线正常工作，我们需要创建一个项目访问令牌，以允许我们调用GitLab的API生成变更日志条目。 创建具有API范围的项目访问令牌，然后将令牌存储为名为CI_API_TOKEN的CI/CD变量。我们将引用此变量来进行API身份验证。

接下来，我们将在gitlab-ci.yml文件中添加两个新任务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
prepare_job:
  stage: prepare
  image: alpine:latest
  # 注释2：
  rules:
  - if: '$CI_COMMIT_TAG =~ /^v?\d+\.\d+\.\d+$/'
  # 注释1：
  script:
    - apk add curl jq
    # 注释2、注释3：
    - 'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG" | jq -r .notes > release_notes.md'
  # 注释1：
  artifacts:
    paths:
    - release_notes.md

release_job:
  stage: release
  # 注释4：
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  needs:
    - job: prepare_job
      artifacts: true
  # 注释2：
  rules:
  - if: '$CI_COMMIT_TAG =~ /^v?\d+\.\d+\.\d+$/'
  script:
    - echo "Creating release"
  # 注释4、注释5：
  release:
    name: 'Release $CI_COMMIT_TAG'
    # 注释6：
    description: release_notes.md
    tag_name: '$CI_COMMIT_TAG'
    ref: '$CI_COMMIT_SHA'
    # 注释7：
    assets:
      links:
        - name: 'Container Image $CI_COMMIT_TAG'
          url: "https://$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA"

在上面的配置中，prepare_job使用curl和jq来调用GitLab Changelog API，然后将其传递给release_job来实际创建发布。

更详细地解释：

  • 注释1：使用之前创建的项目访问令牌调用GitLab Changelog API，以生成发布说明，并将其存储为制品release_notes.md。
  • 注释2：将$CI_COMMIT_TAG变量用作版本。为使其工作，我们需要在标签（Tag）中使用语义版本（例如2.0.0这样的格式），因此您会注意到我还使用rules部分限制了发布任务，以检查是否有语义版本标签（Tag）。
  • 注释3：GitLab Changelog API要求使用语义版本标签（Tag）。它使用此格式查找最近的发布以与当前发布进行比较。
  • 注释4：使用GitLab的官方release-cli镜像。使用release-cli需要在任务中使用release关键字。
  • 注释5：使用release关键字创建GitLab发布。这是专用的作业关键字，用于创建发布并填写所需字段。
  • 注释6：可以将文件作为发布的description参数。在这个例子中，我们将prepare_job中生成的文件，作为制品传递给此作业。
  • 注释7：也可以将流水线中构建的容器镜像作为发布资产包含进来。可以通过提供URL，在流水线中附加任何资产，如二进制文件或文档。（本例中没有演示如何生成容器镜像，并上传到制品库。）

执行自动发布

按照上文进行设置后，要执行发布，我们只需要将一个遵循我们版本规范的标签（Tag）推送到代码库。您可以使用CLI简单地推送一个标签，也可以使用GitLab的UI在主分支上创建标签。通过在侧边栏选择“代码 -> 标签 -> 新建标签”来创建标签：

GitLab UI示例如何在主分支上创建标签的屏幕截图

创建后，流水线将开始自动执行。GitLab Changelog API将自动生成用于发布说明的markdown，其中包含与上一次发布之间的所有更改。以下是在我们示例中生成的markdown的结果：

1
2
3
4
5
6
7
8
9
## 2.0.0 (2023-08-25)

### added (1 change)

- [Add ChatBot](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo@0c3601a45af617c5481322bfce4d71db1f911b02)（[合并请求](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo!4)）

### removed (1 change)

- [Remove Unused Features](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo@463d453c5ae0f4fc611ea969e5442e3298bf0d8a)（[合并请求](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo!3)）

正如您所看到的，GitLab使用我们的git提交追踪器自动提取了发布说明的条目。此外，它还提供了有关变更的更多详细信息和讨论链接，以便读者可以查看。

最终发布如下所示：
The GitLab release UI showing a release for version 2.0.0

创建变更日志

接下来，我们要更新变更日志（所有发布说明的历史记录）。您可以使用POST请求我们之前使用的Changelog API来完成这个操作。

如果您愿意，可以将这个操作作为发布流水线的一部分，例如，将以下内容添加到release任务的script部分：

1
'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" -X POST "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG"

请注意，这会修改代码库。它将创建一个提交，将最新的说明添加到CHANGELOG.md文件中：A screenshot of the repository which shows a commit updating the changelog file

至此，我们就实现了基于git提供的丰富的历史信息和提交追踪器，利用GitLab强大的API和CI/CD流水线来自动化我们的发布流程，并为我们生成发布说明。

教程：使用GitLab自动发布程序并生成发布说明

https://wurang.net/tutorial-automated-release-and-release-notes-with-gitlab/

作者

Wu Rang

发布于

2023-11-06

更新于

2024-06-13

许可协议

#

评论

×