- 查看发布
- 创建发布
- 使用 CI/CD 作业创建发布
- 即将发布
- 编辑发布
- 添加 release notes 到 Git 标签
- 将里程碑与发布相关联
- 创建发布时收到通知
- 通过设置部署冻结来防止意外发布
- 发布字段
- Release evidence
- 发布权限
- 发布命令行
- 发布指标
- 故障排查
发布
要在源代码历史记录中引入检查点,您可以在发布时分配一个 Git 标签。 但是,在大多数情况下,您的用户需要的不仅仅是原始源代码。 他们需要您的 CI/CD 系统输出的编译对象或其他 assets。
极狐GitLab 发布可以是:
- 仓库源代码的快照。
- 从作业产物创建的通用包。
- 与您的代码的已发布版本相关联的其他元数据。
您可以在任何分支上创建 GitLab 版本。 创建发布时:
- 极狐GitLab 自动存档源代码并将其与发布相关联。
- 极狐GitLab 会自动创建一个 JSON 文件,列出发布中的所有内容,以便您可以比较和审核发布。这个文件叫做 release evidence。
- 您可以为与发布相关的标签添加发布说明和消息。
创建发布后,您可以将里程碑与其关联,并附加 release assets,如运行手册或软件包。
查看发布
要查看发布列表:
排序发布
在 发布 页面的右上角,您可以使用排序按钮按 发布日期 或 创建日期 对发布进行排序。您可以按升序或降序对版本进行排序。
创建发布
您可以在用户界面中或使用 Releases API 创建发布。 我们建议使用 API 来创建发布,作为 CI/CD 流水线中的最后一步之一。
只有至少具有开发者角色的用户才能创建发布。 阅读有关发布权限的更多信息。
要通过 GitLab UI 创建新发布:
- 在左侧边栏上,选择 部署 > 发布 并选择 新建发布。
- 打开 标签名称 下拉菜单。选择现有标签或输入新标签名称。选择已与发布关联的现有标签将导致验证错误。
- 如果要创建新标签,请打开 创建自 下拉菜单。选择要在创建新标签时使用的分支、标签或提交 SHA。
- (可选)填写有关发布的任何其他信息,例如其标题、里程碑、release notes或资产链接。
- 点击 创建发布。
使用 CI/CD 作业创建发布
引入于 12.7 版本。
您可以通过在作业定义中使用 release
关键字 直接将发布创建为 GitLab CI/CD 流水线的一部分。
仅当作业处理没有错误时才会创建发布。如果 Rails API 在发布创建期间返回错误,则发布作业将失败。
release
关键字的 CI/CD 示例
要在推送 Git 标签时创建发布,或通过转到 仓库 > 标签 在 UI 中添加 Git 标签时:
release_job:
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
rules:
- if: $CI_COMMIT_TAG # Run this job when a tag is created manually
script:
- echo "running release_job"
release:
name: 'Release $CI_COMMIT_TAG'
description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined
tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline.
ref: '$CI_COMMIT_TAG'
milestones:
- 'm1'
- 'm2'
- 'm3'
released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable.
assets: # Optional, multiple asset links
links:
- name: 'asset1'
url: 'https://example.com/assets/1'
- name: 'asset2'
url: 'https://example.com/assets/2'
filepath: '/pretty/url/1' # optional
link_type: 'other' # optional
要在将提交推送或合并到默认分支时自动创建发布,请使用使用变量定义的新 Git 标签:
prepare_job:
stage: prepare # This stage must run before the release stage
rules:
- if: $CI_COMMIT_TAG
when: never # Do not run this job when a tag is created manually
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch
script:
- echo "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables
- echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file
artifacts:
reports:
dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs
release_job:
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
needs:
- job: prepare_job
artifacts: true
rules:
- if: $CI_COMMIT_TAG
when: never # Do not run this job when a tag is created manually
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch
script:
- echo "running release_job for $TAG"
release:
name: 'Release $TAG'
description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG
tag_name: '$TAG' # variables must be defined elsewhere
ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the
milestones: # prepare_job
- 'm1'
- 'm2'
- 'm3'
released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable.
assets:
links:
- name: 'asset1'
url: 'https://example.com/assets/1'
- name: 'asset2'
url: 'https://example.com/assets/2'
filepath: '/pretty/url/1' # optional
link_type: 'other' # optional
before_script
或 script
中设置的环境变量不可用于在同一作业中扩展。阅读有关潜在地使变量可用于扩展的更多信息。使用自定义 SSL CA 证书颁发机构
您可以使用 ADDITIONAL_CA_CERT_BUNDLE
CI/CD 变量来配置自定义 SSL CA 证书颁发机构,用于在 release-cli
通过 API 使用带有自定义证书的 HTTPS 创建版本时验证对等方。
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-cli
命令行
release
节点下的条目被转换为 bash
命令行并发送到 Docker 容器,其中包含 release-cli。
您还可以直接从 script
条目中调用 release-cli
。
例如,如果您使用前面描述的 YAML:
release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"}
在单个流水线中创建多个发布
一个流水线可以有多个 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'
Release assets as Generic packages
You can use Generic packages to host your release assets. For a complete example, see the Release assets as Generic packages project.
即将发布
您可以使用 Releases API 提前创建发布。
当您设置未来的 released_at
日期时,发布标签旁边会显示 即将发布 徽章。当 released_at
日期和时间过去后,徽章会自动移除。
编辑发布
只有至少具有开发人员角色的用户才能编辑版本。 阅读有关发布权限的更多信息。
要编辑发布的详细信息:
- 在左侧边栏上,选择 部署 > 发布。
- 在您要修改的版本的右上角,单击 编辑此发布(铅笔图标)。
- 在 编辑发布 页面上,更改发布的详细信息。
- 单击 保存修改。
您可以编辑版本标题、注释、关联的里程碑和 assets 链接。 要更改发布日期,请使用 Releases API。
添加 release notes 到 Git 标签
如果您有一个现有的 Git 标签,您可以向其添加 release notes。
您可以在用户界面中执行此操作,也可以使用 Releases API。 我们建议使用 API 添加 release notes,作为 CI/CD 发布流水线中的最后一步。
在界面中,要将 release notes 添加到新的 Git 标签:
- 导航到您项目的 仓库 > 标签。
- 点击 新建标签。
- 在 发布说明 字段中,输入 release notes。您可以使用 Markdown 并将文件拖放到此字段。
- 点击 创建标签。
在界面中,要将 release notes 添加到现有 Git 标签:
- 导航到您项目的 仓库 > 标签。
- 单击 编辑发布说明(铅笔图标)。
- 在 发布说明 字段中,输入 release notes。您可以在此字段中使用 Markdown,并将文件拖放到该字段中。
- 单击 保存修改。
将里程碑与发布相关联
您可以将一个发布与一个或多个项目里程碑相关联。
专业版客户可以指定群组里程碑与发布相关联。
您可以在用户界面中执行此操作,或者通过在对 Releases API 的请求中包含一个 milestones
数组。
在用户界面中,要将里程碑与发布相关联:
- 在左侧边栏上,选择 部署 > 发布。
- 在您要修改的发布的右上角,单击 编辑此发布(铅笔图标)。
- 从 里程碑 列表中,选择要关联的每个里程碑。您可以选择多个里程碑。
- 单击 保存修改。
在 部署 > 发布 页面上,里程碑 列在顶部,以及有关里程碑中议题的统计信息。
在 议题 > 里程碑 页面上以及单击此页面上的里程碑时,也可以看到发布。
下面是一个里程碑示例,分别是没有发布、一个发布和两个发布。
创建发布时收到通知
当为您的项目创建新发布时,您可以通过电子邮件收到通知。
要订阅发布通知:
- 在左侧边栏上,选择 项目信息。
- 点击 通知设置(铃铛图标)。
- 在列表中,单击 自定义。
- 选中 新建版本 复选框。
- 关闭对话框进行保存。
通过设置部署冻结来防止意外发布
- 引入于 13.0 版本。
- 通过 UI 删除冻结期的能力引入于 14.3 版本。
通过设置部署冻结期,在您指定的时间段内防止意外的生产发布。 部署冻结有助于减少自动化部署时的不确定性和风险。
维护者可以在用户界面中设置一个部署冻结窗口,或者通过使用 Freeze Periods API 来设置一个 freeze_start
和一个 freeze_end
,定义为 crontab 条目。
如果正在执行的作业在冻结期内,GitLab CI/CD 会创建一个名为 $CI_DEPLOY_FREEZE
的环境变量。
为了防止部署作业执行,在你的 .gitlab-ci.yml
中创建一个 rules
条目,例如:
deploy_to_production:
stage: deploy
script: deploy_to_prod.sh
rules:
- if: $CI_DEPLOY_FREEZE == null
要在 UI 中设置部署冻结窗口,请完成以下步骤:
- 用具有维护者角色的用户身份登录极狐GitLab。
- 在左侧边栏上,选择 项目信息。
- 在左侧导航菜单中,导航至 设置 > CI/CD。
- 滚动到 部署冻结。
- 点击 展开 查看部署冻结表。
- 点击 添加部署冻结 打开部署冻结窗口。
- 输入所需部署冻结期的开始时间、结束时间和时区。
- 在窗口中点击 添加部署冻结。
-
部署冻结保存后,您可以通过选择编辑按钮()对其进行编辑,并通过选择删除按钮()将其删除。
如果项目包含多个冻结期,则所有冻结期都适用。如果它们重叠,则冻结覆盖整个重叠期。
发布字段
创建或编辑发布时,以下字段可用。
标题
在创建或编辑发布时,可以使用 发布标题 字段自定义发布标题。如果未提供标题,则使用发布的标签名称。
标签名称
发布标签名称应包含发布版本。极狐GitLab 使用语义版本控制发布我们的版本,我们建议您也这样做,使用 (Major).(Minor).(Patch)
。
例如,对于版本 10.5.7
:
-
10
代表主要版本。主要版本是10.0.0
,但通常称为10.0
。 -
5
代表小版本。次要版本是10.5.0
,但通常称为10.5
。 -
7
表示补丁编号。
版本号的任何部分都可以是多个数字,例如 13.10.11
。
Release notes 描述
每个发布都有一个描述。您可以添加任何您喜欢的文本,但我们建议您包含一个更改日志来描述您的版本内容。这有助于用户快速扫描您发布的每个版本之间的差异。
Git 的标记消息 和 release notes 描述无关。说明支持 Markdown。
Release assets
一个版本包含以下类型的 assets:
源代码
极狐GitLab 从给定的 Git 标签自动生成 zip
、tar.gz
、tar.bz2
和 tar
归档源代码。这些是只读 assets。
链接
链接是可以指向您喜欢的任何内容的任何 URL:文档、构建的二进制文件或其他相关材料。这些可以是来自实例的内部或外部链接。 作为 assets 的每个链接都具有以下属性:
属性 | 描述 | 必需 |
---|---|---|
name
| 链接的名称。 | Yes |
url
| 下载文件的 URL。 | Yes |
filepath
| 指向 url 的重定向链接。有关更多信息,请参阅此部分。
| No |
link_type
| 用户可以通过 url 下载的内容类型。有关更多信息,请参阅此部分。
| No |
发布 assets 的永久链接
与发布相关的 assets 可通过永久 URL 访问。 系统始终将此 URL 重定向到实际 assets 位置,因此即使 assets 移动到不同位置,您也可以继续使用相同的 URL。这是在链接创建或更新时定义的。
URL 的格式为:
https://host/namespace/project/releases/:release/downloads/:filepath
链接类型
四种类型的链接是 “Runbook”、“Package”、“Image” 和 “Other”。
link_type
参数接受以下四个值之一:
runbook
package
image
-
other
(默认)
此字段对 URL 没有影响,它仅用于项目的发布页面中的可视化区分。
使用通用包来附加二进制文件
您可以使用通用包存储来自发布或标签流水线的任何产物,也可用于将二进制文件附加到单个发布条目。 基本上,您需要:
- 将产物推送到通用软件包库。
- 将软件包链接附加到发布。
以下示例生成发布 assets,将它们作为通用包发布,然后创建发布:
stages:
- build
- upload
- release
variables:
# Package version can only contain numbers (0-9), and dots (.).
# Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion.
# See https://docs.gitlab.com/ee/user/packages/generic_packages/#publish-a-package-file
PACKAGE_VERSION: "1.2.3"
DARWIN_AMD64_BINARY: "myawesomerelease-darwin-amd64-${PACKAGE_VERSION}"
LINUX_AMD64_BINARY: "myawesomerelease-linux-amd64-${PACKAGE_VERSION}"
PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/myawesomerelease/${PACKAGE_VERSION}"
build:
stage: build
image: alpine:latest
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:
stage: upload
image: curlimages/curl:latest
rules:
- if: $CI_COMMIT_TAG
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}"
release:
# Caution, as of 2021-02-02 these assets links require a login, see:
# https://gitlab.com/gitlab-org/gitlab/-/issues/299384
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
rules:
- if: $CI_COMMIT_TAG
script:
- |
release-cli create --name "Release $CI_COMMIT_TAG" --tag-name $CI_COMMIT_TAG \
--assets-link "{\"name\":\"${DARWIN_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${DARWIN_AMD64_BINARY}\"}" \
--assets-link "{\"name\":\"${LINUX_AMD64_BINARY}\",\"url\":\"${PACKAGE_REGISTRY_URL}/${LINUX_AMD64_BINARY}\"}"
在传递给 release-cli
之前,PowerShell 用户可能需要使用 -assets-link
和 ConvertTo-Json
对 JSON 字符串中的双引号 "
进行转义,并带有 `
(反引号)。
例如:
release:
script:
- $env:asset = "{`"name`":`"MyFooAsset`",`"url`":`"https://gitlab.com/upack/artifacts/download/$env:UPACK_GROUP/$env:UPACK_NAME/$($env:GitVersion_SemVer)?contentOnly=zip`"}"
- $env:assetjson = $env:asset | ConvertTo-Json
- release-cli create --name $CI_COMMIT_TAG --description "Release $CI_COMMIT_TAG" --ref $CI_COMMIT_TAG --tag-name $CI_COMMIT_TAG --assets-link=$env:assetjson
Release evidence
每次创建发布时,系统都会生成与其相关的数据的快照。 此数据保存在 JSON 文件中,称为 release evidence。该功能包括测试产物和链接的里程碑,以促进内部流程,如外部审计。
要访问 release evidence,请在发布页面上,单击 凭证集 标题下列出的 JSON 文件的链接。
您还可以使用 API 为现有发布生成 release evidence。因此,每个发布都可以有多个 release evidence 快照。您可以在发布页面上查看 release evidence 及其详细信息。
禁用议题跟踪器后,无法下载 release evidence。
下面是一个 release evidence 对象的例子:
{
"release": {
"id": 5,
"tag_name": "v4.0",
"name": "New release",
"project": {
"id": 20,
"name": "Project name",
"created_at": "2019-04-14T11:12:13.940Z",
"description": "Project description"
},
"created_at": "2019-06-28 13:23:40 UTC",
"description": "Release description",
"milestones": [
{
"id": 11,
"title": "v4.0-rc1",
"state": "closed",
"due_date": "2019-05-12 12:00:00 UTC",
"created_at": "2019-04-17 15:45:12 UTC",
"issues": [
{
"id": 82,
"title": "The top-right popup is broken",
"author_name": "John Doe",
"author_email": "john@doe.com",
"state": "closed",
"due_date": "2019-05-10 12:00:00 UTC"
},
{
"id": 89,
"title": "The title of this page is misleading",
"author_name": "Jane Smith",
"author_email": "jane@smith.com",
"state": "closed",
"due_date": "nil"
}
]
},
{
"id": 12,
"title": "v4.0-rc2",
"state": "closed",
"due_date": "2019-05-30 18:30:00 UTC",
"created_at": "2019-04-17 15:45:12 UTC",
"issues": []
}
],
"report_artifacts": [
{
"url":"https://gitlab.example.com/root/project-name/-/jobs/111/artifacts/download"
}
]
}
}
收集 release evidence
创建发布时,会自动收集 release evidence。要在任何其他时间启动收集,请使用 API 调用。您可以为一次发布多次收集 release evidence。
在发布页面上可以看到 release evidence 快照以及时间戳。
包括报告产物作为 release evidence
创建发布时,如果作业产物包含在最后运行的流水线中,它们会自动包含在发布中作为 release evidence。
尽管作业产物通常会过期,但 release evidence 中包含的产物不会过期。
要启用作业产物收集,您需要同时指定:
ruby:
script:
- gem install bundler
- bundle install
- bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
artifacts:
paths:
- rspec.xml
reports:
junit: rspec.xml
如果流水线成功运行,当您创建发布时,rspec.xml
文件将保存为 release evidence。
如果您计划 release evidence 收集,一些产物可能在收集时已经过期。为了避免这种情况,您可以使用 artifacts:expire_in
关键字。
计划 release evidence 收集
在 API 中:
- 如果您指定未来的
released_at
日期,则该版本将成为 未来发布,并在发布日期收集 release evidence。在此之前您不能收集 release evidence。 - 如果您使用过去的
released_at
日期,则不会收集任何 release evidence。 - 如果您未指定
released_at
日期,则在创建发布之日收集 release evidence。
发布权限
创建、更新和删除操作的权限窗口修复于 14.1 版本
查看发布并下载 assets
访客角色的访问更改于 14.5 版本。
- 具有报告者或以上角色的用户,具有对项目发布的 read 和下载权限。
- 具有访客角色的用户具有对项目发布的 read 和下载访问权限。包括相关的 Git 标签名称、发布描述、发布的作者信息。但是,其他与仓库相关的信息,例如源代码、release evidence 已被编辑。
创建、更新、删除发布及其 assets
作为发布权限控制的示例,您可以通过保护只允许Maintainer 角色或以上 创建、更新和删除发布 带有通配符 (*
) 的标记,并在 Allowed to create 列中设置 Maintainer。
发布命令行
Release CLI 是一个命令行工具,用于从命令行或 GitLab CI/CD 配置文件 .gitlab-ci.yml
管理 GitLab 发布。
使用它,您可以直接通过终端创建、更新、修改和删除发布。
发布指标
引入于专业版 13.9 版本。
通过导航到 群组 > 分析 > CI/CD,可以获得群组级发布指标。 这些指标包括:
- 群组内发布总数
- 群组中至少有一个发布的项目的百分比
故障排查
在创建、更新或删除版本及其 assets 时出现 403 Forbidden
或 Something went wrong while creating a new release
错误
如果发布与受保护的标签相关联,则 UI/API 请求可能会导致授权失败。 确保用户或服务/机器人帐户也被允许创建受保护的标签。
有关更多信息,请参阅发布权限。