Help us learn about your current experience with the documentation. Take the survey.

发布

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

在关键里程碑处创建发布来打包您的项目。发布将代码、二进制文件、文档和发布说明组合成项目的完整快照。创建发布时，GitLab 会自动为您的代码打标签、存档快照，并生成审计就绪的证据。这创建了一个永久记录，非常适合合规要求，并能让您的用户对您的开发过程充满信心。

您的用户可以受益于：

轻松访问最新的稳定版本和安装包
清晰的新功能和修复文档
能够下载特定版本及其相应的资源
简单跟踪项目随时间的演变

删除与发布关联的 Git 标签也会删除该发布。

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

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

查看发布

要查看发布列表：

在左侧边栏，选择部署 > 发布，或
在项目概览页面上，如果至少存在一个发布，请选择发布数量。
- 在公共项目中，此数字对所有用户可见。
- 在私有项目中，此数字对至少具有 Reporter 角色的用户可见。

排序发布

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

使用 RSS 提要跟踪发布

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

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

创建发布

您可以创建发布：

在发布页面中创建发布

先决条件：

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

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

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

使用 CI/CD 作业创建发布

您可以通过在作业定义中使用 release 关键字，直接作为 GitLab CI/CD 管道的一部分创建发布。您可能应该在 CI/CD 管道的最后步骤之一创建发布。

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

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

使用自定义 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 文件中配置此值，请使用以下内容：

release:
  variables:
    ADDITIONAL_CA_CERT_BUNDLE: |
        -----BEGIN CERTIFICATE-----
        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
        ...
        jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
        -----END CERTIFICATE-----
  script:
    - echo "Create release"
  release:
    name: 'My awesome release'
    tag_name: '$CI_COMMIT_TAG'

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

在单个管道中创建多个发布

管道可以有多个 release 作业，例如：

ios-release:
  script:
    - echo "iOS release job"
  release:
    tag_name: v1.0.0-ios
    description: 'iOS release v1.0.0'

android-release:
  script:
    - echo "Android release job"
  release:
    tag_name: v1.0.0-android
    description: 'Android release v1.0.0'

将发布资源作为通用包

您可以使用通用包来托管您的发布资源。完整示例，请参阅将发布资源作为通用包项目。

要创建带有打包资源的发布：

从 CI/CD 管道中构建您的包文件。

将包文件上传到通用包仓库：

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

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

Create Release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - |
      release-cli create \
      --name "Release ${VERSION}" \
      --tag-name $CI_COMMIT_TAG \
      --description "Your release notes here" \
      --assets-link "{\"name\":\"Asset Name\",\"url\":\"${PACKAGE_REGISTRY_URL}/filename\"}"

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

即将发布的版本

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

历史发布

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

编辑发布

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

先决条件：

您必须至少具有 Developer 角色。

在 UI 中：

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

删除发布

删除发布时，其资源也会被删除。但是，关联的 Git 标签不会被删除。删除与发布关联的 Git 标签也会删除该发布。

先决条件：

您必须至少具有 Developer 角色。有关更多信息，请阅读发布权限。

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

在 UI 中：

在左侧边栏，选择搜索或跳转并找到您的项目。
选择部署 > 发布。
在要删除的发布右上角，选择编辑此发布 （）。
在编辑发布页面，选择删除。
选择删除发布。

将里程碑与发布关联

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

GitLab Premium 客户可以指定组里程碑与发布关联。

您可以在用户界面中执行此操作，或在向发布 API的请求中包含 milestones 数组。

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

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

在部署 > 发布页面上，里程碑列在顶部部分，以及里程碑中问题的统计数据。

发布也显示在计划 > 里程碑页面上，当您选择此页面上的里程碑时。

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

子组的发布无法与父组的里程碑关联。要了解更多信息，请阅读问题 #328054，发布无法与超组里程碑关联。

发布时接收通知

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

要订阅发布通知：

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

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

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

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

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

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

.freezedeployment:
  stage: deploy
  before_script:
    - '[[ ! -z "$CI_DEPLOY_FREEZE" ]] && echo "INFRASTRUCTURE OUTAGE WINDOW" && exit 1; '
  rules:
    - if: '$CI_DEPLOY_FREEZE'
      when: manual
      allow_failure: true
    - when: on_success

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

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

此配置有条件地阻止部署作业并保持管道连续性。当定义冻结期间时，作业失败，管道可以继续执行而无需部署。冻结期间后可以进行手动部署。

这种方法在关键维护期间提供部署控制，并确保 CI/CD 管道的持续流动。

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

以具有 Maintainer 角色的用户身份登录 GitLab。
在左侧边栏，选择搜索或跳转并找到您的项目。
选择设置 > CI/CD。
滚动到部署冻结。
选择展开以查看部署冻结表。
选择添加部署冻结以打开部署冻结模态框。
输入所需的部署冻结期间的开始时间、结束时间和时区。
在模态框中选择添加部署冻结。
部署冻结保存后，您可以通过选择编辑按钮（）进行编辑，并通过选择删除按钮（）删除它。

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

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

发布权限

查看发布和下载资源

至少具有 Reporter 角色的用户可以读取和下载项目发布。
Guest 角色的用户可以读取和下载项目发布。这包括关联的 Git 标签名称、发布说明和发布作者信息。但是，其他存储库相关信息，如源代码和发布证据会被编辑。

不提供源代码访问权限的情况下发布发布

您可以使发布对非项目成员可访问，同时将存储库相关信息（如源代码和发布证据）仅保留给项目成员。这些设置非常适合使用发布提供新软件版本访问权限，但不希望源代码公开可用的项目。

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

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

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

至少具有 Developer 角色的用户对项目发布和资源具有写入权限。
如果发布与受保护标签关联，用户也必须被允许创建受保护标签。

作为发布权限控制的示例，您可以通过使用通配符 (*) 保护标签，并将允许创建列设置为Maintainer，来只允许至少具有 Maintainer 角色的用户创建、更新和删除发布。

发布指标

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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

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

工作示例项目

Guided Exploration 项目使用 GitVersion 完全自动化的软件和工件版本控制演示了：

使用 GitLab 发布。
使用 GitLab release-cli。
创建通用包。
将包链接到发布。
使用名为 GitVersion 的工具自动确定和增加复杂仓库的版本。

您可以将示例项目复制到自己的组或实例进行测试。有关演示的其他 GitLab CI 模式的更多详细信息可在项目页面上找到。

故障排除

创建、更新或删除发布及其资源时出错

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

403 Forbidden
创建新发布时出错

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

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

关于存储的注意事项

此功能基于 Git 标签构建，因此除了创建发布本身外，几乎不需要额外数据。自动生成的附加资源和发布证据会消耗存储。

GitLab CLI 版本要求

使用 release 关键字的方式计划更改。 release-cli 工具正被GitLab CLI 工具取代。

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

Error: glab command not found. Please install glab v1.58.0 or higher.
Error: Please use glab v1.58.0 or higher.
Warning: release-cli will not be supported after 19.0. Please use glab version >= 1.58.0.

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

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

发布

查看发布

排序发布

最新发布的永久链接

排序偏好

使用 RSS 提要跟踪发布

创建发布

在发布页面中创建发布

使用 CI/CD 作业创建发布

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

在单个管道中创建多个发布

将发布资源作为通用包

即将发布的版本

历史发布

编辑发布

删除发布

将里程碑与发布关联

发布时接收通知

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

发布权限

查看发布和下载资源

不提供源代码访问权限的情况下发布发布

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

发布指标

工作示例项目

故障排除

创建、更新或删除发布及其资源时出错

关于存储的注意事项

GitLab CLI 版本要求