Merge pull request #5027 from camilamacedo86/docs-alpha-update

✨ Add plugin for Alpha Update Command

Author: k8s-ci-robot

cmd/cmd.go

@@ -32,6 +32,7 @@ import (
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang"
 	deployimagev1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/deploy-image/v1alpha1"
 	golangv4 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v4"
+	autoupdatev1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/autoupdate/v1alpha"
 	grafanav1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/grafana/v1alpha"
 	helmv1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v1alpha"
 )
@@ -74,6 +75,7 @@ func Run() {
 			&deployimagev1alpha1.Plugin{},
 			&grafanav1alpha1.Plugin{},
 			&helmv1alpha1.Plugin{},
+			&autoupdatev1alpha1.Plugin{},
 		),
 		cli.WithPlugins(externalPlugins...),
 		cli.WithDefaultPlugins(cfgv3.Version, gov4Bundle),

docs/book/src/SUMMARY.md

@@ -120,9 +120,10 @@
 - [Plugins][plugins]
 
   - [Available Plugins](./plugins/available-plugins.md)
+    - [autoupdate/v1-alpha](./plugins/available/autoupdate-v1-alpha.md)
+    - [deploy-image/v1-alpha](./plugins/available/deploy-image-plugin-v1-alpha.md)
     - [go/v4](./plugins/available/go-v4-plugin.md)
     - [grafana/v1-alpha](./plugins/available/grafana-v1-alpha.md)
-    - [deploy-image/v1-alpha](./plugins/available/deploy-image-plugin-v1-alpha.md)
     - [helm/v1-alpha](./plugins/available/helm-v1-alpha.md)
     - [kustomize/v2](./plugins/available/kustomize-v2.md)
   - [Extending](./plugins/extending.md)

docs/book/src/plugins/available/autoupdate-v1-alpha.md

@@ -0,0 +1,67 @@
+# AutoUpdate (`autoupdate/v1-alpha`)
+
+Keeping your Kubebuilder project up to date with the latest improvements shouldn’t be a chore.
+With a small amount of setup, you can receive **automatic Pull Request** suggestions whenever a new
+Kubebuilder release is available — keeping your project **maintained, secure, and aligned with ecosystem changes**.
+
+This automation uses the [`kubebuilder alpha update`][alpha-update-command] command with a **3-way merge strategy** to
+refresh your project scaffold, and wraps it in a GitHub Actions workflow that opens an **Issue** with a **Pull Request compare link** so you can create the PR and review it.
+
+## When to Use It
+
+- When you don’t deviate too much from the default scaffold — ensure that you see the note about customization [here](https://book.kubebuilder.io/versions_compatibility_supportability#project-customizations).
+- When you want to reduce the burden of keeping the project updated and well-maintained.
+
+## How to Use It
+
+0 If you want to add the `autoupdate` plugin to your project:
+
+```shell
+kubebuilder edit --plugins="autoupdate.kubebuilder.io/v1-alpha"
+```
+
+- If you want to create a new project with the `autoupdate` plugin:
+
+```shell
+kubebuilder init --plugins=go/v4,autoupdate/v1-alpha
+```
+
+## How It Works
+
+This will scaffold and GitHub Actions workflow that runs the [kubebuilder alpha update][alpha-update-command] command.
+Then, whenever a new Kubebuilder release is available, it will open an Issue with a
+Pull Request compare link so you can create the PR and review it, such as:
+
+<img width="638" height="482" alt="Example Issue" src="https://github.com/user-attachments/assets/589fd16b-7709-4cd5-b169-fd53d69790d4" />
+
+The workflow will check once a week for new releases, and if there are any, it will create an Issue with a Pull Request compare link so you can create the PR and review it.
+The command called by the workflow is:
+
+```shell
+	# More info: https://kubebuilder.io/reference/commands/alpha_update
+    - name: Run kubebuilder alpha update
+      run: |
+		# Executes the update command with specified flags.
+		# --force: Completes the merge even if conflicts occur, leaving conflict markers.
+		# --push: Automatically pushes the resulting output branch to the 'origin' remote.
+		# --restore-path: Preserves specified paths (e.g., CI workflow files) when squashing.
+		# --open-gh-issue: Creates a GitHub issue with a link to the generated PR for review.
+        kubebuilder alpha update \
+          --force \
+          --push \
+          --restore-path .github/workflows \
+          --open-gh-issue
+```
+
+<aside class="warning">
+<h1>Protect your branches</h1>
+
+This workflow by default **only** creates and pushes the merged files to a branch
+called `kubebuilder-update-from-<from-version>-to-<to-version>`.
+
+To keep your codebase safe, use branch protection rules to ensure that
+changes aren't pushed or merged without proper review.
+
+</aside>
+
+[alpha-update-command]: ./../../reference/commands/alpha_update.md

docs/book/src/plugins/to-add-optional-features.md

@@ -2,12 +2,14 @@
 
 The following plugins are useful to generate code and take advantage of optional features
 
-| Plugin                                            | Key                     | Description                                                                                                                                         |
-|---------------------------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
-| [grafana.kubebuilder.io/v1-alpha][grafana]        | `grafana/v1-alpha`      | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime. |
-| [deploy-image.go.kubebuilder.io/v1-alpha][deploy] | `deploy-image/v1-alpha` | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image).           |
-| [helm.kubebuilder.io/v1-alpha][helm]              | `helm/v1-alpha`         | Optional helper plugin which can be used to scaffold a Helm Chart to distribute the project under the `dist` directory                              |
+| Plugin                                              | Key                     | Description                                                                                                                                                                           |
+|-----------------------------------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [autoupdate.kubebuilder.io/v1-alpha][autoupdate]    | `autoupdate/v1-alpha`   | Optional helper which scaffolds a scheduled worker that helps keep your project updated with changes in the ecosystem, significantly reducing the burden of manual maintenance. |
+| [deploy-image.go.kubebuilder.io/v1-alpha][deploy]   | `deploy-image/v1-alpha` | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image).                                             |
+| [grafana.kubebuilder.io/v1-alpha][grafana]          | `grafana/v1-alpha`      | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime.                                   |
+| [helm.kubebuilder.io/v1-alpha][helm]                | `helm/v1-alpha`         | Optional helper plugin which can be used to scaffold a Helm Chart to distribute the project under the `dist` directory                                                                |
 
 [grafana]: ./available/grafana-v1-alpha.md
 [deploy]: ./available/deploy-image-plugin-v1-alpha.md
-[helm]: ./available/helm-v1-alpha.md
+[helm]: ./available/helm-v1-alpha.md
+[autoupdate]: ./available/autoupdate-v1-alpha.md

docs/book/src/reference/commands/alpha_update.md

@@ -9,6 +9,16 @@ not re-applying your code.
 By default, the final result is **squashed into a single commit** on a dedicated output branch.
 If you prefer to keep the full history (no squash), use `--show-commits`.
 
+<aside class="note">
+<h1>Automate your Updates</h1>
+
+You can reduce the burden of keeping your project up to date by using the
+[`autoupdate.kubebuilder.io/v1-alpha`][autoupdate-plugin] plugin which
+automates the process of running `kubebuilder alpha update` on a schedule
+workflow when new Kubebuilder releases are available.
+
+</aside>
+
 ## When to Use It
 
 Use this command when you:
@@ -207,6 +217,10 @@ so the current behavior may differ slightly from what is shown in the demo.
 
 ## Further Resources
 
-- WIP: Design proposal for update automation — https://github.com/kubernetes-sigs/kubebuilder/pull/4302
+- [AutoUpdate Plugin][autoupdate-plugin]
+- [Design proposal for update automation][design-proposal]
+- [Project configuration reference][project-config]
 
 [project-config]: ../../reference/project-config.md
+[autoupdate-plugin]: ./../../plugins/available/autoupdate-v1-alpha.md
+[design-proposal]: ./../../../../../designs/update_action.md

pkg/cli/alpha/internal/generate.go

@@ -31,6 +31,7 @@ import (
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin/util"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/deploy-image/v1alpha1"
+	autoupdate "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/autoupdate/v1alpha"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/grafana/v1alpha"
 	hemlv1alpha "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v1alpha"
 )
@@ -106,6 +107,10 @@ func (opts *Generate) Generate() error {
 		return fmt.Errorf("error migrating Grafana plugin: %w", err)
 	}
 
+	if err = migrateAutoUpdatePlugin(projectConfig); err != nil {
+		return fmt.Errorf("error migrating AutoUpdate plugin: %w", err)
+	}
+
 	if hasHelmPlugin(projectConfig) {
 		if err = kubebuilderHelmEdit(); err != nil {
 			return fmt.Errorf("error editing Helm plugin: %w", err)
@@ -233,6 +238,23 @@ func migrateGrafanaPlugin(s store.Store, src, des string) error {
 	return kubebuilderGrafanaEdit()
 }
 
+func migrateAutoUpdatePlugin(s store.Store) error {
+	var autoUpdatePlugin struct{}
+	err := s.Config().DecodePluginConfig(plugin.KeyFor(autoupdate.Plugin{}), autoUpdatePlugin)
+	if errors.As(err, &config.PluginKeyNotFoundError{}) {
+		log.Info("Auto Update plugin not found, skipping migration")
+		return nil
+	} else if err != nil {
+		return fmt.Errorf("failed to decode autoupdate plugin config: %w", err)
+	}
+
+	args := []string{"edit", "--plugins", plugin.KeyFor(v1alpha.Plugin{})}
+	if err := util.RunCmd("kubebuilder edit", "kubebuilder", args...); err != nil {
+		return fmt.Errorf("failed to run edit subcommand for Auto plugin: %w", err)
+	}
+	return nil
+}
+
 // Migrates the Deploy Image plugin.
 func migrateDeployImagePlugin(s store.Store) error {
 	var deployImagePlugin v1alpha1.PluginConfig

pkg/cli/alpha/internal/update/update.go

@@ -126,7 +126,7 @@ Create a Pull Request using the URL below to review the changes:
 
 ## Next steps
 
-Verify the changes
+**Verify the changes**
 - Build the project  
 - Run tests  
 - Confirm everything still works

pkg/plugins/optional/autoupdate/v1alpha/edit.go

@@ -0,0 +1,70 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha
+
+import (
+	"fmt"
+
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
+	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
+	"sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/autoupdate/v1alpha/scaffolds"
+)
+
+var _ plugin.EditSubcommand = &editSubcommand{}
+
+type editSubcommand struct {
+	config config.Config
+}
+
+func (p *editSubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
+	subcmdMeta.Description = metaDataDescription
+
+	subcmdMeta.Examples = fmt.Sprintf(`  # Edit a common project with this plugin
+  %[1]s edit --plugins=%[2]s
+`, cliMeta.CommandName, pluginKey)
+}
+
+func (p *editSubcommand) InjectConfig(c config.Config) error {
+	p.config = c
+	return nil
+}
+
+func (p *editSubcommand) PreScaffold(machinery.Filesystem) error {
+	if len(p.config.GetCliVersion()) == 0 {
+		return fmt.Errorf(
+			"you must manually upgrade your project to a version that records the CLI version in PROJECT (`cliVersion`) " +
+				"to allow the `alpha update` command to work properly before using this plugin.\n" +
+				"More info: https://book.kubebuilder.io/migrations",
+		)
+	}
+	return nil
+}
+
+func (p *editSubcommand) Scaffold(fs machinery.Filesystem) error {
+	if err := insertPluginMetaToConfig(p.config, pluginConfig{}); err != nil {
+		return fmt.Errorf("error inserting project plugin meta to configuration: %w", err)
+	}
+
+	scaffolder := scaffolds.NewInitScaffolder()
+	scaffolder.InjectFS(fs)
+	if err := scaffolder.Scaffold(); err != nil {
+		return fmt.Errorf("error scaffolding edit subcommand: %w", err)
+	}
+
+	return nil
+}

pkg/plugins/optional/autoupdate/v1alpha/init.go

@@ -0,0 +1,59 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha
+
+import (
+	"fmt"
+
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
+	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
+	"sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/autoupdate/v1alpha/scaffolds"
+)
+
+var _ plugin.InitSubcommand = &initSubcommand{}
+
+type initSubcommand struct {
+	config config.Config
+}
+
+func (p *initSubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
+	subcmdMeta.Description = metaDataDescription
+
+	subcmdMeta.Examples = fmt.Sprintf(`  # Initialize a common project with this plugin
+  %[1]s init --plugins=%[2]s
+`, cliMeta.CommandName, pluginKey)
+}
+
+func (p *initSubcommand) InjectConfig(c config.Config) error {
+	p.config = c
+	return nil
+}
+
+func (p *initSubcommand) Scaffold(fs machinery.Filesystem) error {
+	if err := insertPluginMetaToConfig(p.config, pluginConfig{}); err != nil {
+		return fmt.Errorf("error inserting project plugin meta to configuration: %w", err)
+	}
+
+	scaffolder := scaffolds.NewInitScaffolder()
+	scaffolder.InjectFS(fs)
+	if err := scaffolder.Scaffold(); err != nil {
+		return fmt.Errorf("error scaffolding init subcommand: %w", err)
+	}
+
+	return nil
+}