✨ alpha(update): add --open-gh-issue flag

[vitorfloriano]

Summary

This PR introduces the --open-gh-issue flag, which enhances the kubebuilder alpha update command with automated GitHub integration and intelligent conflict warning system, making it ready for automated update workflows using GitHub Actions while informing users when manual intervention is needed.

Use Case

When used with GitHub Actions, --open-gh-issue will:

1. Perform an update using a 3-way merge.
2. Create a branch to commit the result.
3. Create an issue to notify about the update, with a link to create a PR.

Issue Template

There's a new scaffold available for update!

Check out what's new in Kubebuilder v4.7.1 Release Notes.

What to do?

To make your life easier, Kubebuilder has updated your project scaffold from v4.6.0 to v4.7.1 on the kubebuilder-alpha-update-from-v4.6.0-to-v4.7.1 branch.

You can create a Pull Request with the changes using the link below:

https://github.com/vitorfloriano/test-operator/pull/new/kubebuilder-alpha-update-from-v4.6.0-to-v4.7.1

ATTENTION: This update was performed by automation. Always review and test your code before merging the changes.

HINT: You can learn more ways to automate updates in the alpha update documentation.

WARNING: Conflict markers were committed to make this automation possible. You should resolve the conflicts before anything.

Idempotency

--open-gh-issue validates if a branch for the same update already exists before pushing anything, which avoids overwritting existing work that may have been started on the update branch.

[k8s-ci-robot]

Hi @vitorfloriano. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[camilamacedo86]

/ok-to-test

[camilamacedo86]

Currently, we just push the branch if we’re in createIssue.
We need to add a check here:

• Check: Do we already have a branch in the repo with outBranchName pushed?
• If yes: Stop the process and show a warning.

The process should end before creating the issue or updating the branch, since we found an existing branch. This is to preserve the existing code and avoid overwriting work. We also won’t open another issue, as it’s likely the task has already been completed.

⚠️ Branch {outBranchName} already exists in the repository.
Skipping issue creation and branch update to preserve existing work.

[vitorfloriano]

createIssue calls pushBranchToRemote, which then calls checkRemoteBranchExists to check that.

If the branch already exists, it logs:

"Remote branch already exists, skipping push to avoid overwriting existing work"

Then we skip issue creation and log:

"Branch was not pushed (already exists), skipping issue creation"

[vitorfloriano]

@camilamacedo86 I did another test just for sanity: https://github.com/vitorfloriano/test-operator/actions/runs/16966361349/job/48091252772#step:5:161

INFO Remote branch already exists, skipping push to avoid overwriting existing work branch=kubebuilder-alpha-update-from-v4.6.0-to-v4.7.1
INFO Branch was not pushed (already exists), skipping issue creation branch=kubebuilder-alpha-update-from-v4.6.0-to-v4.7.1

The branch was not pushed and did not overwrite the existent one.

[vitorfloriano]

But looking at the code again, we could reorder the checks so this message would be shown regardless of whether the issue already existed or the branch already existed. 🤔

[camilamacedo86]

INFO Branch was not pushed (already exists), skipping issue creation branch=kubebuilder-alpha-update-from-v4.6.0-to-v4.7.1

The second one can be only from skipping

[vitorfloriano]

@camilamacedo86 , I improved the logic and logging to behave as follows:

Case 1: Both branch & issue exist (most common re-run)

Scenario: User runs the command again after everything was already created

INFO Remote branch already exists. Branch was not pushed to avoid overwriting existing work
INFO Issue for update already exists. Nothing to do here. from=v4.5.0 to=v4.6.0

Case 2: Branch exists, no issue (issue was deleted/never created)

Scenario: Branch was created before but issue creation failed or was manually deleted

INFO Remote branch already exists. Branch was not pushed to avoid overwriting existing work
INFO Creating issue for existing branch branch=kubebuilder-alpha-update-from-v4.5.0-to-v4.6.0

(issue creation proceeds normally)

Case 3: Branch doesn't exist, issue exists (branch was deleted/failed to push)

Scenario: Issue exists but branch was manually deleted or push failed previously
(pushBranchToRemote logs from successful push operation)
INFO Branch was created but issue already exists for this update branch=kubebuilder-alpha-update-from-v4.5.0-to-v4.6.0

WDYT?

[camilamacedo86]

/lgtm
/approved

Let's move forward, to facilitate the progress and we can refine in follow-up if we need. !
Great work 🎉

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, vitorfloriano

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

New changes are detected. LGTM label has been removed.

[camilamacedo86]

/hold

I think in a way to simplify it.
I will try to do it today

[vitorfloriano]

Closed in favor of #5018.