chore(alpha update/AutoUpdate): Changes to ensure better usage and allow granular workflow and permissions

Author: camilamacedo86

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

@@ -16,7 +16,7 @@ jobs:
   auto-update:
     permissions:
       contents: write  # Create and push the update branch
-      issues: write    # Create GitHub Issue with PR link
+      pull-requests: write  # Create Pull Request
     runs-on: ubuntu-latest
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -57,15 +57,15 @@ jobs:
       # --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-pr: Creates a GitHub Pull Request directly for review.
       #
       # WARNING: This workflow does not use GitHub Models AI summary by default.
-      # To enable AI-generated summaries in GitHub issues, you need permissions to use GitHub Models.
+      # To enable AI-generated summaries, you need permissions to use GitHub Models.
       # If you have the required permissions, re-run:
       #   kubebuilder edit --plugins="autoupdate/v1-alpha" --use-gh-models
       run: |
         kubebuilder alpha update \
           --force \
           --push \
           --restore-path .github/workflows \
-          --open-gh-issue
+          --open-gh-pr

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

@@ -5,7 +5,7 @@ With a small amount of setup, you can receive **automatic Pull Request** suggest
 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.
+refresh your project scaffold, and wraps it in a GitHub Actions workflow that **creates Pull Requests** for review. Alternatively, you can use `--only-issue` to create Issues instead of PRs.
 
 <aside class="warning" role="note">
 <p class="note-title">Protect your branches</p>
@@ -41,12 +41,14 @@ kubebuilder init --plugins=go/v4,autoupdate/v1-alpha
 ### Optional: GitHub Models AI Summary
 
 By default, the workflow works without GitHub Models to avoid permission errors.
-If you want AI-generated summaries in your update issues:
+If you want AI-generated summaries in your update Pull Requests:
 
 ```shell
 kubebuilder edit --plugins="autoupdate/v1-alpha" --use-gh-models
 ```
 
+**Note:** AI summaries only work with Pull Requests (the default). If you use `--only-issue`, you cannot use `--use-gh-models`.
+
 <aside class="note" role="note">
 <p class="note-title">Permissions required to use GitHub Models in GitHub Actions</p>
 
@@ -71,13 +73,9 @@ Your organization or enterprise may have disabled it. Contact your administrator
 The plugin scaffolds a GitHub Actions workflow that checks for new Kubebuilder releases every week. When an update is available, it:
 
 1. Creates a new branch with the merged changes
-2. Opens a GitHub Issue with a PR compare link
-
-**Example Issue:**
+2. Opens a Pull Request for review (or an Issue if you use `--only-issue`)
 
-<img width="638" height="482" alt="Example Issue" src="https://github.com/user-attachments/assets/589fd16b-7709-4cd5-b169-fd53d69790d4" />
-
-**With GitHub Models enabled** (optional), you also get AI-generated summaries:
+**With GitHub Models enabled** (optional), you get AI-generated summaries in the PR description:
 
 <img width="582" height="646" alt="AI Summary" src="https://github.com/user-attachments/assets/d460a5af-5ca4-4dd5-afb8-7330dd6de148" />
 
@@ -93,8 +91,8 @@ The generated workflow uses the `kubebuilder alpha update` command with default
 - `--force` - Continue even if conflicts occur (automation-friendly)
 - `--push` - Automatically push the output branch to remote
 - `--restore-path .github/workflows` - Preserve CI workflows from base branch
-- `--open-gh-issue` - Create a GitHub Issue with PR compare link
-- `--use-gh-models` - (optional) Add AI summary to the issue
+- `--open-gh-pr` - Create a GitHub Pull Request for review
+- `--use-gh-models` - (optional) Add AI summary to the PR description
 
 **Additional available flags:**
 - `--merge-message` - Custom commit message for clean merges
@@ -118,11 +116,19 @@ Edit `.github/workflows/auto_update.yml`:
       --force \
       --push \
       --restore-path .github/workflows \
-      --open-gh-issue \
+      --open-gh-pr \
       --merge-message "chore: update kubebuilder scaffold" \
       --conflict-message "chore: update with conflicts - review needed"
 ```
 
+**Example: Create Issues instead of PRs**
+
+If you prefer to receive update notifications as GitHub Issues (without AI summaries):
+
+```shell
+kubebuilder edit --plugins="autoupdate/v1-alpha" --only-issue
+```
+
 ## Troubleshooting
 
 #### If you get the 403 Forbidden Error
@@ -144,7 +150,7 @@ This regenerates the workflow without GitHub Models:
 ```yaml
 permissions:
   contents: write
-  issues: write
+  pull-requests: write
   # No models: read permission
 
 steps:
@@ -162,7 +168,7 @@ steps:
         --force \
         --push \
         --restore-path .github/workflows \
-        --open-gh-issue
+        --open-gh-pr
 ```
 
 The workflow continues to work—just without AI summaries.
@@ -182,7 +188,7 @@ This regenerates the workflow WITH GitHub Models:
 ```yaml
 permissions:
   contents: write
-  issues: write
+  pull-requests: write
   models: read  # Added for GitHub Models
 
 steps:
@@ -196,14 +202,13 @@ steps:
       gh models --help >/dev/null
 
   - name: Run kubebuilder alpha update
-    # --use-gh-models: Adds an AI-generated comment to the Issue with
-    #   a summary of scaffold changes and conflict-resolution guidance (if any).
+    # --use-gh-models: Adds an AI summary to the PR description.
     run: |
       kubebuilder alpha update \
         --force \
         --push \
         --restore-path .github/workflows \
-        --open-gh-issue \
+        --open-gh-pr \
         --use-gh-models
 ```
 

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

@@ -68,8 +68,9 @@ The command creates three temporary branches:
     - `--conflict-message`: customize the commit message when conflicts occur.
     - `--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`: add an AI overview **comment** to that issue using `gh models`
+    - `--open-gh-issue`: create a GitHub issue with instructions to run update locally (requires `gh`).
+    - `--open-gh-pr`: create a GitHub pull request directly after the update (requires `gh`). **(requires branch name to start with `kubebuilder-update-from-`)**
+    - `--use-gh-models`: add an AI summary to the PR description using `gh models` (only works with `--open-gh-pr`)
 
 ### Step 5: Cleanup
 - Once the output branch is ready, all the temporary working branches are deleted.
@@ -157,41 +158,61 @@ make manifests generate fmt vet lint-fix
 make all
 ```
 
-## Using with GitHub Issues (`--open-gh-issue`) and AI (`--use-gh-models`) assistance
+## Using with GitHub (`--open-gh-issue` / `--open-gh-pr`) 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.
+### Creating GitHub Issues (`--open-gh-issue`)
 
-### Examples
+Pass `--open-gh-issue` to have the command create a GitHub **Issue** in your repository with instructions
+to run the update locally. This requires minimal permissions (read repo, write issues).
 
-Create an Issue with a compare link:
+**Example:**
 ```shell
 kubebuilder alpha update --open-gh-issue
 ```
 
-Create an Issue **and** add an AI summary:
+The Issue will contain:
+- Upgrade description with release notes links
+- Instructions to run `alpha update` locally
+- Note about updating your GitHub Action workflow
+
+### Creating Pull Requests Directly (`--open-gh-pr`)
+
+Pass `--open-gh-pr` to have the command create a GitHub **Pull Request** directly after the update completes.
+This requires write permissions for contents and pull requests.
+
+**Example:**
 ```shell
-kubebuilder alpha update --open-gh-issue --use-gh-models
+kubebuilder alpha update --open-gh-pr
 ```
 
-### What you’ll see
+With `--use-gh-models`, the AI summary is added to the PR description:
+```shell
+kubebuilder alpha update --open-gh-pr --use-gh-models
+```
 
-The command opens an Issue that links to the diff so you can create the PR and review it, for example:
+The PR will include:
+- Upgrade description with release notes links
+- Conflict warnings if any were detected
+- AI-generated summary of changes (if `--use-gh-models` is used)
 
-<img width="638" height="482" alt="Example Issue" src="https://github.com/user-attachments/assets/589fd16b-7709-4cd5-b169-fd53d69790d4" />
+<aside class="warning" role="note">
+    <p class="note-title">Security: Branch Name Validation</p>
+
+For security reasons, `--open-gh-pr` can only be used with branches that start with `kubebuilder-update-from-`.
+This prevents accidentally creating PRs from arbitrary branches. The default output branch already follows this pattern.
 
-With `--use-gh-models`, an AI comment highlights key changes and suggests how to resolve any conflicts:
+</aside>
 
-<img width="740" height="425" alt="Comment" src="https://github.com/user-attachments/assets/fb5f214e-be0e-43b8-a3fb-b5744ac8f66e" />
+**Important:** `--open-gh-issue` and `--open-gh-pr` are mutually exclusive. Choose one based on your workflow and permissions.
+
+### What you’ll see
 
-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:
+With `--use-gh-models`, AI models help you understand what changes are needed to keep your project up to date,
+and suggest resolutions if conflicts are encountered.
 
 ### 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.
+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). By default, it creates Pull Requests directly, but you can use `--only-issue` to create Issues instead.
 
 ## Changing Extra Git configs only during the run (does not change your ~/.gitconfig)_
 
@@ -241,13 +262,14 @@ We use that value to pick the correct CLI for re-scaffolding.
 | `--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`. |
 | `--merge-message`            | Custom commit message for successful merges (no conflicts). Defaults to `chore(kubebuilder): update scaffold <from> -> <to>`.                                                                                                           |
-| `--open-gh-issue`  | Create a GitHub issue with a pre-filled checklist and compare link after the update completes (requires `gh`).                                                                                                                          |
+| `--open-gh-issue`  | Create a GitHub issue with instructions to run update locally (requires `gh`). Mutually exclusive with `--open-gh-pr`.                                                                                                                  |
+| `--open-gh-pr`     | Create a GitHub pull request directly after the update completes (requires `gh`). Mutually exclusive with `--open-gh-issue`. **Security:** Branch name must start with `kubebuilder-update-from-`.                                      |
 | `--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`. Requires `gh` + `gh-models` extension. Effective only when `--open-gh-issue` is also set.                                                                                    |
+| `--use-gh-models`  | Generate an AI summary using `gh models` and add it to the PR description. Requires `gh` + `gh-models` extension. Only works with `--open-gh-pr`.                                                                                      |
 | `-h, --help`       | Show help for this command.                                                                                                                                                                                                             |
 
 ## Demonstration

internal/cli/alpha/internal/generate.go

@@ -328,6 +328,9 @@ func migrateAutoUpdatePlugin(s store.Store) error {
 	if autoUpdatePlugin.UseGHModels {
 		args = append(args, "--use-gh-models")
 	}
+	if autoUpdatePlugin.OnlyIssue {
+		args = append(args, "--only-issue")
+	}
 	if err = util.RunCmd("kubebuilder edit", "kubebuilder", args...); err != nil {
 		return fmt.Errorf("failed to run edit subcommand for Auto plugin: %w", err)
 	}

internal/cli/alpha/internal/update/helpers/open_gh_issue.go

@@ -36,73 +36,34 @@ const (
 // IssueTitleTmpl is the title template for the GitHub issue.
 const IssueTitleTmpl = "[Action Required] Upgrade the Scaffold: %[2]s -> %[1]s"
 
-// IssueBodyTmpl is used when no conflicts are detected during the merge.
+// CommonDescriptionTmpl is the base description used for both issues and PRs.
+// Parameters: [1]=toVersion, [2]=fromVersion
 //
 //nolint:lll
-const IssueBodyTmpl = `## Description
+const CommonDescriptionTmpl = `## Description
 
-Upgrade your project to use the latest scaffold changes introduced in Kubebuilder [%[1]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[1]s).  
+Upgrade project to use the scaffold changes introduced in Kubebuilder [%[1]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[1]s).
 
-See the release notes from [%[3]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[3]s) to [%[1]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[1]s) for details about the changes included in this upgrade.
-
-## What to do
-
-A scheduled workflow already attempted this upgrade and created the branch %[4]s to help you in this process.
-
-Create a Pull Request using the URL below to review the changes:
-%[2]s  
-
-## Next steps
-
-**Verify the changes**
-- Build the project  
-- Run tests  
-- Confirm everything still works
-
-:book: **More info:** https://kubebuilder.io/reference/commands/alpha_update
+See the release notes from [%[2]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[2]s) to [%[1]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[1]s) for details about the changes included in this upgrade.
 `
 
-// IssueBodyTmplWithConflicts is used when conflicts are detected during the merge.
+// IssueBodyTmpl is the complete issue body template.
+// Parameters: [1]=toVersion, [2]=fromVersion
 //
 //nolint:lll
-const IssueBodyTmplWithConflicts = `## Description
-
-Upgrade your project to use the latest scaffold changes introduced in Kubebuilder [%[1]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[1]s).  
-
-See the release notes from [%[3]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[3]s) to [%[1]s](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/%[1]s) for details about the changes included in this upgrade.
-
+const IssueBodyTmpl = CommonDescriptionTmpl + `
 ## What to do
 
-A scheduled workflow already attempted this upgrade and created the branch (%[4]s) to help you in this process.
-
-:warning: **Conflicts were detected during the merge.**
-
-Create a Pull Request using the URL below to review the changes and resolve conflicts manually:
-%[2]s  
+Run the command ` + "`alpha update`" + ` locally. This upgrades your scaffold and preserves your changes using a 3-way merge.
 
-## Next steps
+More info: https://kubebuilder.io/reference/commands/alpha_update
 
-### 1. Resolve conflicts
-After fixing conflicts, run:
-~~~bash
-make manifests generate fmt vet lint-fix
-~~~
-
-### 2. Optional: work on a new branch
-To apply the update in a clean branch, run:
-~~~bash
-kubebuilder alpha update --output-branch my-fix-branch
-~~~
-
-This will create a new branch (my-fix-branch) with the update applied.  
-Resolve conflicts there, complete the merge locally, and push the branch.
+> Note: If you want to automate PR creation, use the latest Kubebuilder release and run: ` + "`kubebuilder edit --plugins=\"autoupdate/v1-alpha\" --force`" + `
+`
 
-### 3. Verify the changes
-- Build the project  
-- Run tests  
-- Confirm everything still works
+// ConflictWarningForIssue is prepended to "What to do" section when conflicts exist.
+const ConflictWarningForIssue = `:warning: **Conflicts were detected during the merge.**
 
-:book: **More info:** https://kubebuilder.io/reference/commands/alpha_update
 `
 
 // AiPRPrompt is the prompt to `gh models run`.