图表发布工具

帮助将GitHub仓库转化为Helm图表仓库

cr是一个工具，旨在帮助GitHub仓库自托管其图表仓库。它通过将Helm图表制品添加到以图表版本命名的GitHub发布中，然后为这些发布创建一个index.yaml文件，该文件可以托管在GitHub Pages（或其他地方）上。

安装

二进制文件（推荐）

从发布页面下载您喜欢的资源并手动安装。

Homebrew

$ brew tap helm/tap
$ brew install chart-releaser

Go get（用于贡献）

// 将仓库克隆到GOPATH之外的某个目录

$ git clone https://github.com/helm/chart-releaser
$ cd chart-releaser
$ go mod download
$ go install ./...

Docker（用于持续集成）

Docker镜像推送到helmpack/chart-releaser Quay容器注册表。Docker镜像构建在Alpine之上，其默认入口点是cr。有关更多详细信息，请参阅Dockerfile。

常见用法

目前，cr可以从打包到目录中的一组图表创建GitHub发布，并从GitHub发布中为图表仓库创建index.yaml文件。

$ cr --help
通过将图表包和图表元数据上传到GitHub发布并创建适当的索引文件，在GitHub Pages上创建Helm图表仓库

用法：
  cr [命令]

可用命令：
  completion  为指定的shell生成自动完成脚本
  help        关于任何命令的帮助
  index       更新给定GitHub仓库的Helm仓库index.yaml
  package     打包Helm图表
  upload      将Helm图表包上传到GitHub发布
  version     打印版本信息

标志：
      --config string   配置文件（默认为$HOME/.cr.yaml）
  -h, --help            cr的帮助

使用"cr [命令] --help"获取有关命令的更多信息。

处理有依赖关系的图表

不幸的是，发布工具不会自动为依赖项添加仓库，这需要在运行发布工具之前添加到您的流水线中（示例），如下所示：

    - name: 添加仓库
        run: |
          helm repo add bitnami https://charts.bitnami.com/bitnami
          helm repo add bitnami-pre2022 https://raw.githubusercontent.com/bitnami/charts/eb5f9a9513d987b519f0ecd732e7031241c50328/bitnami

      - name: 运行chart-releaser
        uses: helm/chart-releaser-action@v1.6.0
        with:
          charts_dir: config/helm-chart
        env:
          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

从Helm图表包创建GitHub发布

扫描路径中的Helm图表包，并在指定的GitHub仓库中创建发布，上传这些包。

$ cr upload --help
将Helm图表包上传到GitHub发布

用法：
  cr upload [标志]

标志：
  -c, --commit string                  发布的目标提交
      --generate-release-notes         是否自动生成此发布的名称和正文。参见https://docs.github.com/en/rest/releases/releases
  -b, --git-base-url string            GitHub基础URL（仅私有GitHub需要）（默认为"https://api.github.com/"）
  -r, --git-repo string                GitHub仓库
  -u, --git-upload-url string          GitHub上传URL（仅私有GitHub需要）（默认为"https://uploads.github.com/"）
  -h, --help                           upload的帮助
  -o, --owner string                   GitHub用户名或组织
  -p, --package-path string            图表包目录的路径（默认为".cr-release-packages"）
      --release-name-template string   用于计算发布名称的Go模板，使用图表元数据（默认为"{{ .Name }}-{{ .Version }}"）
      --release-notes-file string      带有图表发布说明的Markdown文件。如果设置为空字符串，或找不到文件，将使用图表描述。从图表包中读取文件
      --skip-existing                  如果发布已存在则跳过上传
  -t, --token string                   GitHub认证令牌
      --make-release-latest bool       将创建的GitHub发布标记为"最新"（默认为"true"）
      --packages-with-index            在GitHub Pages分支中托管包文件

全局标志：
      --config string   配置文件（默认为$HOME/.cr.yaml）

从GitHub发布创建仓库索引

上传完成后，您可以创建一个index.yaml文件，该文件可以托管在GitHub Pages（或其他地方）上。

$ cr index --help
根据给定GitHub仓库的发布更新Helm图表仓库index.yaml文件。

用法：
  cr index [标志]

标志：
  -b, --git-base-url string            GitHub基础URL（仅私有GitHub需要）（默认为"https://api.github.com/"）
  -r, --git-repo string                GitHub仓库
  -u, --git-upload-url string          GitHub上传URL（仅私有GitHub需要）（默认为"https://uploads.github.com/"）
  -h, --help                           index的帮助
  -i, --index-path string              索引文件的路径（默认为".cr-index/index.yaml"）
  -o, --owner string                   GitHub用户名或组织
  -p, --package-path string            图表包目录的路径（默认为".cr-release-packages"）
      --pages-branch string            GitHub pages分支（默认为"gh-pages"）
      --pages-index-path string        GitHub pages索引路径（默认为"index.yaml"）
      --pr                             为index.yaml创建针对GitHub Pages分支的拉取请求（如果设置了--push则不能设置）
      --push                           将index.yaml推送到GitHub Pages分支（如果设置了--pr则不能设置）
      --release-name-template string   用于计算发布名称的Go模板，使用图表元数据（默认为"{{ .Name }}-{{ .Version }}"）
      --remote string                  创建GitHub Pages分支本地工作树时使用的Git远程（默认为"origin"）
  -t, --token string                   GitHub认证令牌（仅私有仓库需要）
      --packages-with-index            在GitHub Pages分支中托管包文件

全局标志：
      --config string   配置文件（默认为$HOME/.cr.yaml）

在私有仓库中使用

在私有仓库中使用此工具时，helm无法下载图表包文件。当您向Helm提供用户名和密码时，它用于验证仓库（索引文件）。然后索引文件告诉Helm在哪里获取tarball。如果tarball托管在其他位置（在本例中为GitHub发布），则需要第二次身份验证（Helm不支持）。解决方案是将文件托管在与索引文件相同的位置，并使链接为相对路径，这样就不需要第二次身份验证。

#123通过在上传和索引命令中添加--packages-with-index标志来解决这个问题。

先决条件

拥有具有正确权限的Github令牌（企业版启用SSO）并配置GitHub Pages。

用法

以下是使图表最终托管在GitHub页面根目录并可访问的三个命令：

cr package <chart>

cr upload --owner <owner> --git-repo <repo_name> --packages-with-index --token <token> --push --skip-existing

不要忘记在上传命令中使用--skip-existing标志，以避免出现422 Validation Failed错误。

cr index --owner <owner> --git-repo <repo_name>  --packages-with-index --index-path . --token <token> --push

示例

在仓库根目录中有一个testChart helm图表：

cr package testChart/

您将在**./cr-release-pacakges**中获得.tgz文件

repository

执行以下两个命令：

cr upload --owner <owner> --git-repo <repo_name> --packages-with-index --token <token> --push --skip-existing

cr index --owner <owner> --git-repo <repo_name>  --packages-with-index --index-path . --token <token> --push

您应该在github-pages分支的根目录中获得图表的发布以及.tgz文件。

github pages

index.yaml引用每个图表及其不同版本：

index

配置

cr 是一个命令行应用程序。所有命令行标志也可以通过环境变量或配置文件设置。环境变量必须以 CR_ 为前缀。必须使用下划线代替连字符。

CLI 标志、环境变量和配置文件可以混合使用。以下优先顺序适用：

CLI 标志
环境变量
配置文件

示例

以下示例展示了配置相同内容的各种方式：

CLI

cr upload --owner myaccount --git-repo helm-charts --package-path .deploy --token 123456789

环境变量

export CR_OWNER=myaccount
export CR_GIT_REPO=helm-charts
export CR_PACKAGE_PATH=.deploy
export CR_TOKEN="123456789"
export CR_GIT_BASE_URL="https://api.github.com/"
export CR_GIT_UPLOAD_URL="https://uploads.github.com/"
export CR_SKIP_EXISTING=true

cr upload

配置文件

config.yaml:

owner: myaccount
git-repo: helm-charts
package-path: .deploy
token: 123456789
git-base-url: https://api.github.com/
git-upload-url: https://uploads.github.com/

配置使用

cr upload --config config.yaml

cr 支持 Viper 可以读取的任何格式，即 JSON、TOML、YAML、HCL 和 Java 属性文件。

请注意，如果未指定配置文件，cr.yaml（或任何支持的格式）将按顺序从当前目录、$HOME/.cr 或 /etc/cr 加载（如果找到的话）。

Github Enterprise 用户注意事项

对于 Github Enterprise，chart-releaser 用户需要正确设置 git-base-url 和 git-upload-url，但正确的值对最终用户来说并不总是显而易见的。

默认情况下，它们通常类似于以下形式：

https://ghe.example.com/api/v3/
https://ghe.example.com/api/uploads/

如果您正在尝试确定您的 upload_url 是什么，可以尝试使用像这样的 curl 命令： curl -u username:token https://example.com/api/v3/repos/org/repo/releases 然后查找 upload_url。您需要 URL 中路径中 repos/ 之前出现的部分。

常见错误消息

在上传过程中，您可能会遇到以下错误：

422 Validation Failed [{Resource:Release Field:tag_name Code:already_exists Message:}]

您可以通过在命令中添加 --skip-existing 标志来解决这个问题。更多详细信息可以在 #101 和解决这个问题的 #111 中找到。

已知 Bug

目前，如果您错误地设置了上传 URL，比如设置为 https://example.com/uploads/，那么 cr upload 看起来会正常工作，但实际上发布并不完整。正常情况下，每个发布应该有三个资产，但此时只会有两个源代码资产。第三个资产缺失，而这是 Helm 所需要的。当您运行 cr index 时，这个问题就会变得明显，因为它总是声称没有任何变化，这是因为它找不到预期的发布资产。

看起来 go-github Do 调用没有捕获上传 URL 不正确的情况，也没有传回预期的错误。如果资产上传失败，最好是回滚（删除）发布，并向用户显示适当的日志消息。

cr index 命令还应该在发布没有附加任何资产时生成警告，以帮助用户检测和解决此类问题。