使用 alpha update 升级项目

概述

kubebuilder alpha update 通过 Git 的三方合并将你的项目脚手架升级到更新的 Kubebuilder 版本。它会为旧版本与新版本分别重建干净的脚手架，将你当前的代码合并进新的脚手架，并生成一个便于审阅的输出分支。它负责繁重工作，让你专注于审阅与解决冲突，而不是重复应用你的代码。

默认情况下，最终结果会在专用输出分支上被压缩为单个提交（squash）。若希望保留完整历史（不 squash），请使用 --show-commits。

适用场景

在以下情况下使用该命令：

• 希望迁移到更新的 Kubebuilder 版本或插件布局
• 希望在独立分支上审阅脚手架变更
• 希望专注于解决合并冲突（而非重复应用自定义代码）

工作原理

你需要告知工具“目标版本”以及当前项目所在的分支。它会重建两个脚手架，并通过“三方合并”将你的代码并入新脚手架，最后给出一个可供审阅与安全合并的输出分支。你可以决定是只保留一个干净提交、保留完整历史，还是自动推送到远端。

第一步：检测版本

• 读取 PROJECT 文件或命令行参数
• 通过 PROJECT 文件中的 cliVersion 字段（若存在）确定“来源版本”
• 确定“目标版本”（默认最新发布版本）
• 选择当前代码所在分支（默认 main）

第二步：创建脚手架

命令会创建三个临时分支：

• Ancestor：来自旧版本的干净项目脚手架
• Original：你的当前代码快照
• Upgrade：来自新版本的干净脚手架

第三步：执行三方合并

• 使用 Git 的三方合并将 Original（你的代码）合并到 Upgrade（新脚手架）
• 在引入上游变更的同时保留你的自定义
• 如果发生冲突：
  • 默认：停止并让你手动解决
  • 使用 --force：即使存在冲突标记也继续提交（适合自动化）
• 运行 make manifests generate fmt vet lint-fix 进行整理

第四步：写入输出分支

• 默认情况下，所有变更会在一个安全的输出分支上被压缩为单个提交：kubebuilder-update-from-<from-version>-to-<to-version>
• 你可以调整行为：
  • --show-commits：保留完整历史
  • --restore-path：在 squash 模式下，从基分支恢复特定文件（例如 CI 配置）
  • --output-branch：自定义输出分支名
  • --push：自动推送结果到 origin
  • --git-config：设置 Git 配置
  • --open-gh-issue：创建带检查清单与对比链接的 GitHub Issue（需要 gh）
  • --use-gh-models：使用 gh models 向 Issue 添加 AI 概览评论

第五步：清理

• 输出分支就绪后，所有临时工作分支会被删除
• 你会得到一个干净的分支，可用于测试、审阅并合并回主分支

如何使用（命令）

Run from your project root:

kubebuilder alpha update

固定版本与基分支：

kubebuilder alpha update \
--from-version v4.5.2 \
--to-version   v4.6.0 \
--from-branch  main

适合自动化（即使发生冲突也继续）：

kubebuilder alpha update --force

保留完整历史而非 squash：

kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --show-commits

默认 squash，但保留基分支中的 CI/workflows：

kubebuilder alpha update --force \
--restore-path .github/workflows \
--restore-path docs

使用自定义输出分支名：

kubebuilder alpha update --force \
--output-branch upgrade/kb-to-v4.7.0

执行更新并将结果推送到 origin：

kubebuilder alpha update --from-version v4.6.0 --to-version v4.7.0 --force --push

处理冲突（--force 与默认行为）

使用 --force 时，即使存在冲突 Git 也会完成合并。提交中会包含如下冲突标记：

<<<<<<< HEAD
Your changes
=======
Incoming changes
>>>>>>> (original)

This allows you to run the command in CI or cron jobs without manual intervention.

• Without --force: the command stops on the merge branch and prints guidance; no commit is created.
• With --force: the merge is committed (merge or output branch) and contains the markers.

After you fix conflicts, always run:

make manifests generate fmt vet lint-fix
# or
make all

Using with GitHub Issues (--open-gh-issue) and AI (--use-gh-models) assistance

Pass --open-gh-issue to have the command create a GitHub Issue in your repository to assist with the update. Also, if you also pass --use-gh-models, the tool posts a follow-up comment on that Issue with an AI-generated overview of the most important changes plus brief conflict-resolution guidance.

Examples

Create an Issue with a compare link:

kubebuilder alpha update --open-gh-issue

Create an Issue and add an AI summary:

kubebuilder alpha update --open-gh-issue --use-gh-models

What you’ll see

The command opens an Issue that links to the diff so you can create the PR and review it, for example:

With --use-gh-models, an AI comment highlights key changes and suggests how to resolve any conflicts:

Moreover, AI models are used to help you understand what changes are needed to keep your project up to date, and to suggest resolutions if conflicts are encountered, as in the following example:

Automation

This integrates cleanly with automation. The autoupdate.kubebuilder.io/v1-alpha plugin can scaffold a GitHub Actions workflow that runs the command on a schedule (e.g., weekly). When a new Kubebuilder release is available, it opens an Issue with a compare link so you can create the PR and review it.

Changing Extra Git configs only during the run (does not change your ~/.gitconfig)_

By default, kubebuilder alpha update applies safe Git configs: merge.renameLimit=999999, diff.renameLimit=999999, merge.conflictStyle=merge You can add more, or disable them.

• Add more on top of defaults

kubebuilder alpha update \
  --git-config rerere.enabled=true

• Disable defaults entirely

kubebuilder alpha update --git-config disable

• Disable defaults and set your own

kubebuilder alpha update \
  --git-config disable \
  --git-config rerere.enabled=true

参数

演示

更多资源

• AutoUpdate Plugin
• Design proposal for update automation
• Project configuration reference