发布

创建发布#

创建一个发布来在关键里程碑时打包您的项目。发布将代码、二进制文件、文档和发布说明结合成项目的完整快照。当创建发布时，极狐GitLab 会自动标记您的代码，存档快照，并生成符合审计要求的证据。这创建了一个永久记录，非常适合合规要求，并可以增强用户对您开发过程的信心。

您的用户将受益于：

• 轻松访问最新的稳定版本和安装软件包
• 关于新功能和修复的清晰文档
• 能够下载特定版本及其对应的资产
• 简单的方法来跟踪项目随时间的演变

创建发布时，或者之后，您可以：

• 添加发布说明。
• 为与发布关联的 Git 标签添加消息。
• 将里程碑与其关联。
• 附加发布资产，如运行手册或软件包。

查看发布#

要查看发布列表：

1. 在左侧边栏中，选择 部署 > 发布，或

2. 在项目概览页面上，如果至少存在一个发布，选择发布的数量。

• 在公共项目中，这个数字对所有用户可见。
• 在私有项目中，这个数字对至少拥有报告者角色的用户可见。

排序发布#

要按发布日期或创建日期排序发布，请从排序顺序下拉列表中选择。要在升序或降序之间切换，请选择排序顺序。

最新发布的永久链接#

您可以通过永久链接访问最新发布页面。极狐GitLab 始终将永久链接 URL 重定向到最新发布页面的地址。

URL 的格式为：

plaintext
https://gitlab.example.com/namespace/project/-/releases/permalink/latest

您还可以向永久链接 URL 添加后缀。例如，如果最新发布是 v17.7.0#release 在 gitlab-org 命名空间和 gitlab-runner 项目中，可读的链接将是：

plaintext
https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v17.7.0#release

您可以通过以下永久链接访问最新发布 URL：

plaintext
https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest#release

要了解有关向发布资产添加永久链接的信息，请参阅最新发布资产的永久链接。

排序偏好#

默认情况下，极狐GitLab 使用 released_at 时间获取发布。使用查询参数 ?order_by=released_at 是可选的。

使用 RSS 提要跟踪发布#

极狐GitLab 提供项目发布的 Atom 格式的 RSS 提要。要查看提要：

1. 对于您是成员的项目：
   1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
   2. 选择 部署 > 发布。
2. 对于所有项目：
   1. 转到项目概览页面。
   2. 在右侧边栏中，选择 发布 (
      )。
3. 在右上角，选择提要符号 (
   )。

创建发布#

您可以创建发布：

1. 使用 CI/CD 流水线中的作业。
2. 在发布页面中。
3. 使用 发布 API。

在发布页面中创建发布#

前提条件：

• 您必须至少拥有项目的开发者角色。更多信息，请阅读发布权限。

要在发布页面中创建发布：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > 发布 并选择 新建发布。
3. 从 标签名称 下拉列表中，选择：
   • 选择一个现有的 Git 标签。选择已经与发布关联的现有标签会导致验证错误。
   • 输入一个新的 Git 标签名称。
     1. 从 创建标签 弹出窗口中，选择创建新标签时要使用的分支或提交 SHA。
     2. 可选。在 设置标签消息 文本框中，输入消息以创建带注释的标签。
     3. 选择 保存。
4. 可选。输入有关发布的附加信息，包括：
   • 标题。
   • 里程碑。
   • 发布说明。
   • 是否包含标签消息。
   • 资产链接。
5. 选择 创建发布。

使用 CI/CD 作业创建发布#

您可以通过在作业定义中使用 release 关键字，直接在极狐GitLab CI/CD 流水线中创建发布。您可能希望将发布创建作为 CI/CD 流水线的最后一个步骤之一。

只有当作业处理无错误时才会创建发布。如果在创建发布期间 API 返回错误，发布作业将失败。

以下链接显示了使用 CI/CD 作业创建发布的典型配置示例：

1. 当创建 Git 标签时创建发布。
2. 当提交合并到默认分支时创建发布。
3. 在自定义脚本中创建发布元数据。

使用自定义 SSL CA 证书颁发机构#

您可以使用 ADDITIONAL_CA_CERT_BUNDLE CI/CD 变量配置自定义 SSL CA 证书颁发机构，用于在 release-cli 使用自定义证书通过 HTTPS 通过 API 创建发布时验证对等方。ADDITIONAL_CA_CERT_BUNDLE 值应包含 X.509 PEM 公钥证书的文本表示或包含证书颁发机构的 path/to/file。例如，要在 .gitlab-ci.yml 文件中配置此值，请使用以下内容：

yaml
1release:
2  variables:
3    ADDITIONAL_CA_CERT_BUNDLE: |
4        -----BEGIN CERTIFICATE-----
5        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
6        ...
7        jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
8        -----END CERTIFICATE-----
9  script:
10    - echo "Create release"
11  release:
12    name: 'My awesome release'
13    tag_name: '$CI_COMMIT_TAG'

ADDITIONAL_CA_CERT_BUNDLE 值也可以配置为 UI 中的自定义变量，可以作为 file，需要证书路径，或作为变量，需文本表示的证书。

在单个流水线中创建多个发布#

一个流水线可以有多个 release 作业，例如：

yaml
1ios-release:
2  script:
3    - echo "iOS release job"
4  release:
5    tag_name: v1.0.0-ios
6    description: 'iOS release v1.0.0'
7
8android-release:
9  script:
10    - echo "Android release job"
11  release:
12    tag_name: v1.0.0-android
13    description: 'Android release v1.0.0'

发布资产作为通用软件包#

您可以使用通用软件包来托管您的发布资产。

要创建包含打包资产的发布：

1. 从 CI/CD 流水线构建您的软件包文件。

2. 将软件包文件上传到通用软件包存储库：

   yaml
   1Upload Package:
   2  stage: deploy
   3script:
   4  - |
   5    curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
   6     --upload-file path/to/your/file \
   7     ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${PACKAGE_NAME}/${VERSION}/filename

3. 使用 release-cli 作业创建发布：

   yaml
   1Create Release:
   2  stage: release
   3  image: registry.gitlab.com/gitlab-org/release-cli:latest
   4  rules:
   5    - if: $CI_COMMIT_TAG
   6  script:
   7    - |
   8      release-cli create \
   9      --name "Release ${VERSION}" \
   10      --tag-name $CI_COMMIT_TAG \
   11      --description "Your release notes here" \
   12      --assets-link "{\"name\":\"Asset Name\",\"url\":\"${PACKAGE_REGISTRY_URL}/filename\"}"

   对于您想要包含的每个资产，添加一个额外的 --assets-link 链接。

即将发布#

您可以通过使用发布 API提前创建发布。当您设置一个未来的 released_at 日期时，会在发布标签旁显示一个即将发布徽章。当 released_at 日期和时间过去后，徽章会自动移除。

历史发布#

您可以使用发布 API或 UI 创建过去的发布。当您设置一个过去的 released_at 日期时，会在发布标签旁显示一个历史发布徽章。由于是在过去发布的，发布证据不可用。

编辑发布#

要在创建发布后编辑其详细信息，您可以使用更新发布 API或 UI。

前提条件：

• 您必须至少拥有开发者角色。

在 UI 中：

1. 在左侧边栏中，选择 部署 > 发布。
2. 在您想要修改的发布的右上角，选择 编辑此发布（铅笔图标）。
3. 在 编辑发布 页面，更改发布的详细信息。
4. 选择 保存更改。

删除发布#

当您删除一个发布时，其资产也会被删除。但是，关联的 Git 标签不会被删除。删除与发布关联的 Git 标签也会删除发布。

前提条件：

• 您必须至少拥有开发者角色。阅读更多关于发布权限。

要删除发布，请使用删除发布 API或 UI。

在 UI 中：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
2. 选择 部署 > 发布。
3. 在您想要删除的发布的右上角，选择 编辑此发布 (
   )。
4. 在 编辑发布 页面，选择 删除。
5. 选择 删除发布。

将里程碑与发布关联#

您可以将发布与一个或多个项目里程碑关联。

极狐GitLab 专业版客户可以指定群组里程碑与发布关联。

您可以在用户界面中执行此操作，或者在请求中包括一个 milestones 数组 通过发布 API。

在用户界面中，要将里程碑与发布关联：

1. 在左侧边栏中，选择 部署 > 发布。
2. 在您想要修改的发布的右上角，选择 编辑此发布（铅笔图标）。
3. 从 里程碑 列表中，选择您想要关联的每个里程碑。您可以选择多个里程碑。
4. 选择 保存更改。

在 部署 > 发布 页面，里程碑 列在顶部部分，以及里程碑中的议题统计信息。

发布也可见于 计划 > 里程碑 页面，并且当您在此页面上选择一个里程碑时。

以下是没有发布、一个发布和两个发布的里程碑示例。

在创建发布时获取通知#

当为您的项目创建新发布时，您可以通过电子邮件获取通知。

要订阅发布通知：

1. 在左侧边栏中，选择 项目概览。
2. 选择 通知设置（铃铛图标）。
3. 在列表中，选择 自定义。
4. 选择 新发布 复选框。
5. 关闭对话框以保存。

通过设置部署冻结来防止意外发布#

通过设置部署冻结期间，防止在您指定的时间段内意外的生产发布。部署冻结有助于在自动化部署时减少不确定性和风险。

维护者可以在用户界面中设置部署冻结窗口，或使用 Freeze Periods API 设置 freeze_start 和 freeze_end，定义为 crontab 条目。

如果正在执行的作业处于冻结期间，极狐GitLab CI/CD 会创建一个名为 $CI_DEPLOY_FREEZE 的环境变量。

要防止部署作业在群组中的多个项目中执行，请在群组中共享的文件中定义 .freezedeployment 作业。使用 includes 关键字将模板合并到项目的 .gitlab-ci.yml 文件中：

yaml
1.freezedeployment:
2  stage: deploy
3  before_script:
4    - '[[ ! -z "$CI_DEPLOY_FREEZE" ]] && echo "INFRASTRUCTURE OUTAGE WINDOW" && exit 1; '
5  rules:
6    - if: '$CI_DEPLOY_FREEZE'
7      when: manual
8      allow_failure: true
9    - when: on_success

要防止部署作业执行，请在 .gitlab-ci.yml 文件的 deploy_to_production 作业中使用 extends 关键字继承 .freezedeployment 模板作业的配置：

yaml
deploy_to_production:
  extends: .freezedeployment
  script: deploy_to_prod.sh
  environment: production

此配置有条件地阻止部署作业，并保持流水线的连续性。当定义了冻结期时，作业会失败，流水线可以在不进行部署的情况下继续。在冻结期之后，可以手动部署。

这种方法在关键维护期间提供了部署控制，并确保 CI/CD 流水线的不间断流动。

要在 UI 中设置部署冻结窗口，请完成以下步骤：

1. 以维护者角色身份登录极狐GitLab。
2. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
3. 选择 设置 > CI/CD。
4. 滚动到 部署冻结。
5. 选择 展开 以查看部署冻结表。
6. 选择 添加部署冻结 以打开部署冻结模式。
7. 输入所需的部署冻结期间的开始时间、结束时间和时区。
8. 在模式中选择 添加部署冻结。
9. 保存部署冻结后，您可以通过选择编辑按钮 (
   ) 进行编辑，并通过选择删除按钮 (
   ) 删除它。

如果项目包含多个冻结期，则所有期间适用。如果它们重叠，冻结将覆盖完整的重叠期间。

有关更多信息，请参阅部署安全性。

发布权限#

查看发布和下载资产#

• 具有至少报告者角色的用户具有项目发布的读取和下载访问权限。
• 具有访客角色的用户具有项目发布的读取和下载访问权限。这包括关联的 Git 标签名称、发布说明、发布作者信息。然而，其他与存储库相关的信息，例如源代码和发布证据会被隐藏。

发布发布而不授予对源代码的访问权限#

您可以在不将与存储库相关的信息（例如源代码和发布证据）公开的情况下，使发布对非项目成员可访问。这些设置适合使用发布来提供软件新版本访问的项目，但不希望源代码公开可用。

要使发布公开可用，请设置以下项目设置：

• 项目可见性 设置为 公开
• 存储库 启用并设置为 仅项目成员
• 发布 启用并设置为 有访问权限的所有人

创建、更新和删除发布及其资产#

• 具有至少开发者角色的用户具有项目发布和资产的写入权限。
• 如果发布与受保护的标签关联，则用户还必须被允许创建受保护的标签。

作为发布权限控制的示例，您可以通过使用通配符（*）保护标签，并在允许创建列中设置维护者，仅允许至少具有维护者角色的用户创建、更新和删除发布。

发布指标#

通过导航到 群组 > 分析 > CI/CD，可以获得群组级别的发布指标。这些指标包括：

• 群组中的发布总数
• 群组中至少有一个发布的项目百分比

故障排除#

创建、更新或删除发布及其资产时的错误#

如果发布与受保护的标签关联，则 UI/API 请求可能会导致授权失败，例如：

• 403 Forbidden
• Something went wrong while creating a new release

确保用户或服务/机器人帐户也被允许创建受保护的标签。

有关更多信息，请参阅发布权限。

关于存储的说明#

此功能建立在 Git 标签之上，因此除了创建发布本身外几乎不需要额外的数据。自动生成的额外资产和发布证据会消耗存储。

极狐GitLab CLI 版本要求#

使用 release 关键字 的方式计划更改。

您必须使用极狐GitLab CLI 工具 v1.53.0 或更高版本，否则您可能会收到以下错误消息或警告：

• Error: glab command not found. Please install glab v1.53.0 or higher.
• Error: Please use glab v1.53.0 or higher.
• Warning: release-cli will not be supported after 18.0. Please use glab version >= 1.53.0.

有两种方式获取极狐GitLab CLI 工具：

• 如果您使用 registry.gitlab.com/gitlab-org/release-cli:<version> 容器镜像，您可以开始使用 registry.gitlab.com/gitlab-org/cli:v1.53.0 或 registry.gitlab.com/gitlab-org/release-cli:v0.22.0，其中包含 glab v1.53.0。
• 如果您在您的 runner 上手动安装了 release-cli 或极狐GitLab CLI 工具，请确保极狐GitLab CLI 版本至少为 v1.53.0。