chore(alpha update command): add option to use ai with gh models

Assisted-by: ChatGPT (OpenAI)

Co-authored-by: Vitor Floriano <vitorfloriano@users.noreply.github.com>

Author: camilamacedo86

docs/book/src/getting-started.md

@@ -408,6 +408,19 @@ The [Manager][manager] in the `cmd/main.go` file is responsible for managing the
 ```
 </details>
 
+### Use Kubebuilder plugins to scaffold additional options
+
+Now that you have a better understanding of how to create your own API and controller,
+let’s scaffold in this project the plugin [`autoupdate.kubebuilder.io/v1-alpha`][autoupdate-plugin]
+so that your project can be kept up to date with the latest Kubebuilder releases scaffolding changes
+and consequently adopt improvements from the ecosystem.
+
+```shell
+kubebuilder edit --plugins="autoupdate/v1-alpha"
+```
+
+Inspect the file `.github/workflows/auto-update.yml` to see how it works.
+
 ### Checking the Project running in the cluster
 
 At this point you can check the steps to validate the project
@@ -444,3 +457,4 @@ implemented for your controller.
 [deploy-image]: ./plugins/available/deploy-image-plugin-v1-alpha.md
 [GOPATH-golang-docs]: https://golang.org/doc/code.html#GOPATH
 [go-modules-blogpost]: https://blog.golang.org/using-go-modules
+[autoupdate-plugin]: ./plugins/available/autoupdate-v1-alpha.md

docs/book/src/getting-started/testdata/project/.github/workflows/auto_update.yml

@@ -0,0 +1,74 @@
+name: Auto Update
+
+# The 'kubebuilder alpha update 'command requires write access to the repository to create a branch
+# with the update files and allow you to open a pull request using the link provided in the issue.
+# The branch created will be named in the format kubebuilder-update-from-<from-version>-to-<to-version> by default.
+# To protect your codebase, please ensure that you have branch protection rules configured for your 
+# main branches. This will guarantee that no one can bypass a review and push directly to a branch like 'main'.
+permissions:
+  contents: write
+  issues: write
+  models: read
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * 2" # Every Tuesday at 00:00 UTC
+
+jobs:
+  auto-update:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    # Step 1: Checkout the repository.
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        fetch-depth: 0
+    
+    # Step 2: Configure Git to create commits with the GitHub Actions bot.
+    - name: Configure Git
+      run: |
+        git config --global user.name "github-actions[bot]"
+        git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+    # Step 3: Set up Go environment.
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: stable
+
+    # Step 4: Install Kubebuilder.
+    - name: Install Kubebuilder
+      run: |
+        curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
+        chmod +x kubebuilder
+        sudo mv kubebuilder /usr/local/bin/
+        kubebuilder version
+
+    # Step 5: Install Models extension for GitHub CLI
+    - name: Install/upgrade gh-models extension
+      run: |
+        gh extension install github/gh-models --force
+        gh models --help >/dev/null
+
+    # Step 6: Run the Kubebuilder alpha update command.
+    # 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 for opening a PR for review.
+       # --open-gh-models: Adds an AI-generated comment to the created Issue with
+       #   a short overview of the scaffold changes and conflict-resolution guidance (If Any).
+        kubebuilder alpha update \
+          --force \
+          --push \
+          --restore-path .github/workflows \
+          --open-gh-issue \
+          --use-gh-models

docs/book/src/getting-started/testdata/project/PROJECT

@@ -7,6 +7,7 @@ domain: example.com
 layout:
 - go.kubebuilder.io/v4
 plugins:
+  autoupdate.kubebuilder.io/v1-alpha: {}
   helm.kubebuilder.io/v1-alpha: {}
 projectName: project
 repo: example.com/memcached

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

@@ -11,10 +11,12 @@ refresh your project scaffold, and wraps it in a GitHub Actions workflow that op
 
 - 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.
+- When you want to guidance and help from AI to know what changes are needed to keep your project up to date
+as to solve conflicts.
 
 ## How to Use It
 
-0 If you want to add the `autoupdate` plugin to your project:
+- If you want to add the `autoupdate` plugin to your project:
 
 ```shell
 kubebuilder edit --plugins="autoupdate.kubebuilder.io/v1-alpha"
@@ -28,12 +30,26 @@ 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:
+This will scaffold a GitHub Actions workflow that runs the [kubebuilder alpha update][alpha-update-command] command.
+Whenever a new Kubebuilder release is available, the workflow will automatically open an **Issue** with a Pull Request compare link so you can easily 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" />
 
+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:
+
+<img width="663" height="613" alt="AI Comment Example" src="https://github.com/user-attachments/assets/49562851-2936-4204-a11d-8205fcef9370" />
+
+You will also see a list of files changed, making it easier to review the updates:
+
+<img width="692" height="590" alt="AI files changed" src="https://github.com/user-attachments/assets/9518f1ba-3718-4e51-a1fb-0735b56aa0f9" />
+
+If conflicts arise, AI-generated comments will guide you step by step through the resolution process:
+
+<img width="691" height="311" alt="Conflict Example" src="https://github.com/user-attachments/assets/036663d2-dd69-4f99-a63d-c10a96458815" />
+
+### Workflow details
+
 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:
 
@@ -45,12 +61,14 @@ The command called by the workflow is:
 		# --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.
+		# --open-gh-models: Adds an AI-generated comment to the created Issue with
+		#   a short overview of the scaffold changes and conflict-resolution guidance (If Any).
         kubebuilder alpha update \
           --force \
           --push \
           --restore-path .github/workflows \
-          --open-gh-issue
+          --open-gh-issue \
+          --use-gh-models
 ```
 
 <aside class="warning">

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

@@ -17,6 +17,9 @@ You can reduce the burden of keeping your project up to date by using the
 automates the process of running `kubebuilder alpha update` on a schedule
 workflow when new Kubebuilder releases are available.
 
+Moreover, you will be able to get help from AI models to understand what changes are needed to keep your project up to date
+and how to solve conflicts if any be faced.
+
 </aside>
 
 ## When to Use It
@@ -27,6 +30,7 @@ Use this command when you:
 - Prefer automation over manual file editing
 - Want to review scaffold changes on a separate branch
 - Want to focus on resolving merge conflicts (not re-applying your custom code)
+- Want an **AI-generated** overview of changes and guidance for resolving conflicts
 
 ## How It Works
 
@@ -64,6 +68,9 @@ The command creates three temporary branches:
     - `--output-branch`: pick a custom branch name.
     - `--push`: push the result to `origin` automatically.
     - `--git-config`: sets git configurations.
+    - `--open-gh-issue`: create a GitHub issue with a checklist and compare link (requires `gh`).
+    - `--use-gh-models[=<model>]`: add an AI overview **comment** to that issue using `gh models`
+    (requires the `gh-models` extension). If used without a value, default
 
 ### Step 5: Cleanup
 - Once the output branch is ready, all the temporary working branches are deleted.
@@ -143,7 +150,56 @@ make manifests generate fmt vet lint-fix
 make all
 ```
 
-### Changing Extra Git configs only during the run (does not change your ~/.gitconfig)_
+## 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 with:
+- a pre-filled checklist of follow-up steps, and
+- a compare link so you can open a PR and review the update.
+
+If you also pass `--use-gh-models[=<model>]`, 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. When the flag is provided without a value, the default model is `openai/gpt-4o`. The AI comment uses simple, Kubebuilder-style wording and, when relevant, adds a short **Conflicts** section with commands to regenerate files. *(If the `gh models` command isn’t available, the Issue is still created; only the AI comment is skipped.)*
+
+> **Tip:** You can run with `--dry-run` first to preview changes locally, then re-run with `--open-gh-issue` (and optionally `--use-gh-models`) when you’re ready to file the Issue.
+
+### Examples
+
+Create an Issue with a compare link:
+```shell
+kubebuilder alpha update --open-gh-issue
+```
+
+Create an Issue **and** add an AI summary using the default model:
+```shell
+kubebuilder alpha update --open-gh-issue --use-gh-models
+```
+Choose a specific GitHub-hosted model:
+
+```shell
+kubebuilder alpha update --open-gh-issue --use-gh-models=openai/gpt-4o
+```
+
+### What you’ll see
+
+When a new Kubebuilder release is available, the command opens an Issue that links to the diff so you can create the PR and review it, for example:
+
+<img width="638" height="482" alt="Example Issue" src="https://github.com/user-attachments/assets/589fd16b-7709-4cd5-b169-fd53d69790d4" />
+
+With `--use-gh-models`, an AI comment highlights key changes and suggests how to resolve any conflicts (e.g., which files to regenerate and which commands to run):
+
+<img width="663" height="613" alt="AI Comment Example" src="https://github.com/user-attachments/assets/49562851-2936-4204-a11d-8205fcef9370" />
+
+You’ll also get a concise list of changed files to streamline the review:
+
+<img width="692" height="590" alt="AI files changed" src="https://github.com/user-attachments/assets/9518f1ba-3718-4e51-a1fb-0735b56aa0f9" />
+
+If conflicts arise, AI-generated comments call them out and provide next steps:
+
+<img width="691" height="311" alt="Conflict Example" src="https://github.com/user-attachments/assets/036663d2-dd69-4f99-a63d-c10a96458815" />
+
+### Automation
+
+This integrates cleanly with automation. The [`autoupdate.kubebuilder.io/v1-alpha`][autoupdate-plugin] 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`.
@@ -171,18 +227,20 @@ kubebuilder alpha update \
 
 ## Flags
 
-| Flag               | Description                                                                                                                                                                                                                            |
-|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--from-version`   | Kubebuilder release to update **from** (e.g., `v4.6.0`). If unset, read from the `PROJECT` file when possible.                                                                                                                         |
-| `--to-version`     | Kubebuilder release to update **to** (e.g., `v4.7.0`). If unset, defaults to the latest available release.                                                                                                                             |
-| `--from-branch`    | Git branch that holds your current project code. Defaults to `main`.                                                                                                                                                                   |
-| `--force`          | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (CI/cron friendly).                                                                                                                      |
-| `--show-commits`   | Keep full history (do not squash). **Not compatible** with `--preserve-path`.                                                                                                                                                          |
-| `--restore-path`   | Repeatable. Paths to preserve from the base branch (repeatable). Not supported with --show-commits. (e.g., `.github/workflows`).                                                                                                       |
-| `--output-branch`  | Name of the output branch. Default: `kubebuilder-update-from-<from-version>-to-<to-version>`.                                                                                                                                          |
-| `--push`           | Push the output branch to the `origin` remote after the update completes.                                                                                                                                                              |
-| `--git-config`     | Repeatable. Pass per-invocation Git config as `-c key=value`. **Default** (if omitted): `-c merge.renameLimit=999999 -c diff.renameLimit=999999`. Your configs are applied on top. To disable defaults, include `--git-config disable` |
-| `-h, --help`       | Show help for this command.                                                                                                                                                                                                            |
+| Flag               | Description                                                                                                                                                                                                                                      |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--force`          | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (CI/cron friendly).                                                                                                                                |
+| `--from-branch`    | Git branch that holds your current project code. Defaults to `main`.                                                                                                                                                                             |
+| `--from-version`   | Kubebuilder release to update **from** (e.g., `v4.6.0`). If unset, read from the `PROJECT` file when possible.                                                                                                                                   |
+| `--git-config`     | Repeatable. Pass per-invocation Git config as `-c key=value`. **Default** (if omitted): `-c merge.renameLimit=999999 -c diff.renameLimit=999999`. Your configs are applied on top. To disable defaults, include `--git-config disable`.          |
+| `--open-gh-issue`  | Create a GitHub issue with a pre-filled checklist and compare link after the update completes (requires `gh`).                                                                                                                                   |
+| `--output-branch`  | Name of the output branch. Default: `kubebuilder-update-from-<from-version>-to-<to-version>`.                                                                                                                                                    |
+| `--push`           | Push the output branch to the `origin` remote after the update completes.                                                                                                                                                                        |
+| `--restore-path`   | Repeatable. Paths to preserve from the base branch when squashing (e.g., `.github/workflows`). **Not supported** with `--show-commits`.                                                                                                          |
+| `--show-commits`   | Keep full history (do not squash). **Not compatible** with `--restore-path`.                                                                                                                                                                     |
+| `--to-version`     | Kubebuilder release to update **to** (e.g., `v4.7.0`). If unset, defaults to the latest available release.                                                                                                                                       |
+| `--use-gh-models`  | Post an AI overview as an issue comment using `gh models`. Provide a model name; if the flag is used without a value it defaults to `openai/gpt-4o`. Requires `gh` + `gh-models` extension. Effective only when `--open-gh-issue` is also set.   |
+| `-h, --help`       | Show help for this command.                                                                                                                                                                                                                      |
 
 <aside class="note warning">
 <h1>You might need to upgrade your project first</h1>

hack/docs/internal/getting-started/generate_getting_started.go

@@ -219,6 +219,12 @@ func (sp *Sample) GenerateSampleProject() {
 		"--resource", "--controller",
 	)
 	hackutils.CheckError("Creating the API", err)
+
+	slog.Info("Adding AutoUpdate Plugin")
+	err = sp.ctx.Edit(
+		"--plugins", "autoupdate/v1-alpha",
+	)
+	hackutils.CheckError("Initializing the getting started project", err)
 }
 
 // CodeGen will call targets to generate code