Yusong

Appearance

Create Releases ​

文档用途

说明 GitLab Release 的适用场景与使用方法.

写在前面 ​

GitLab 和 GitHub 都有名为 Release 的功能, 并且几乎是一样的.
Release 常会添加描述, 用于说明这个版本的改动 (类似 CHANGELOG.md).
在 Assets 中, 经常会包含应用程序的安装包或可执行文件.

GitLab 官方文档 对于 Release 这个功能介绍非常准确.

In GitLab, a release enables you to create a snapshot of your project for your users, including installation packages and release notes.

Releases ​

在代码仓库的 Deploy / Releases 查看或创建新的 release.

某个 release 如下图所示.

INFO

Release 中的代码仓库压缩包中, 会包含 Git LFS 文件, 因此是完整的工程.
首次下载的时候速度比较慢, 估计是因为 GitLab 会一边压缩一边传输 (而不是提前把压缩包制作好).

仓库主页 ​

在代码仓库的主页, 可以看到所有的 Release.

Milestone ​

在创建新的 Release 时, 可以选择与之关联的 Milestone.
之后在 Milestones 页面, 就可以看到与某个与之关联的 Release.

毕竟不是所有工程都会遵循 Keep a changelog (需要手动维护 CHANGELOG.md).
但由于 Release 关联 Milestone, 而 Milestone 关联 Issues,
这就让某个 Release 的改动自然而然地呈现出来, 没有任何额外的工作.

Git Tags ​

GitLab Release 与 Git Tag 有密切的关系:

  • 必须使用唯一的 Git Tag 来创建 Release, 若没有合适的 Tag 则需要新建.
  • 如果 Git Tag 被删除, 那么与之相关的 Release 也会被自动删除.
  • 在 Git Tag 的网页, 每个 Tag 的右侧都有 Create Release 按钮.

Assets ​

INFO

参考官方示例工程 Release assets as Generic packages.

在 GitLab Release 中的 Assets 包含两部分: 源代码压缩包和其他.
而源代码压缩包是自动生成的, 我们只需要手动设置其他 Assets (提供名称和 url).

为了提供长期有效地 url, 我们应该将镜像上传 Container Registry,
将安装包等文件作为 Generic Package 上传 Package Registry.

用于上传 Package Registry 的 CI/CD Job
yaml
variables:
  # Package version should match \A(\.?[\w\+-]+\.?)+\z regular expresion.
  # See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file
  PACKAGE_VERSION: $CI_COMMIT_TAG
  DARWIN_AMD64_BINARY: "my-release-darwin-amd64-${PACKAGE_VERSION}"
  LINUX_AMD64_BINARY: "my-release-linux-amd64-${PACKAGE_VERSION}"
  PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my-release/${PACKAGE_VERSION}"

build-package:
  image: alpine
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - mkdir bin
    - echo "Mock binary for ${DARWIN_AMD64_BINARY}" > bin/${DARWIN_AMD64_BINARY}
    - echo "Mock binary for ${LINUX_AMD64_BINARY}" > bin/${LINUX_AMD64_BINARY}
  artifacts:
    paths:
      - bin/

upload-package:
  image: curlimages/curl
  rules:
    - if: $CI_COMMIT_TAG
  needs:
    - job: build-package
  script:
    - |
      curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
        --upload-file bin/${DARWIN_AMD64_BINARY} \
        ${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}
    - |
      curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
        --upload-file bin/${LINUX_AMD64_BINARY} \
        ${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}

为了避免 Package Registry 占用过多的存储空间, 建议做如下设置:
在代码仓库的 Settings / Packages and registries 中,
将 Number of duplicate assets to keep 设置为 1.

在 Group 的 Settings / Packages and registries 中也可以做设置,
这会影响 Group 中所有的代码仓库.

CI/CD ​

我们可以通过 CI/CD Job 来创建 Release, 借助 Job 中的 release 字段.
常见使用场景: 当远程仓库检查到新的 Git Tag 被创建时, 自动执行用于创建 Release 的 Job.

参考官方文档 CI/CD YAML syntax reference - GitLab Docs.
以及 Create a release when a git tag is created - GitLab Docs.

yaml
release_job:
  stage: release
  # Executor 为 docker 的 gitlab-runner 需要使用此镜像.
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    # 当 Git Tag 被创建时, 执行此 Job.
    - if: $CI_COMMIT_TAG
  script:
    - echo "running release_job"
  release:
    tag_name: '$CI_COMMIT_TAG'
    description: '$CI_COMMIT_TAG'

INFO

在 CI/CD Job 中使用 release 字段时, 实际上是使用了 release-cli 命令.
因此必须让 gitlab-runner 能找到 release-cli 命令, 为此就需要提供包含此命令的镜像.
而对于 executor 为 shell 的 gitlab-runner, 则需要在宿主系统中安装 release-cli 可执行文件.
详见 GitLab Release CLI tool - GitLab Docs.