Bug: CI Allows merge of incomplete changes

[theunrepentantgeek]

Describe the bug

In #3206, we merged an update to cache without fully updating the index files used by our documentation. The docs were missing links to the samples.

Every CI build since then has failed because files are detected as modified during the CI process.

This is a bug in our CI process - this should not have been able to occur.

To Reproduce

Unclear how to reproduce, as I thought we'd fixed this. It may be due to @matthchr working from a fork.

Expected behavior

After merge of any PR, running task ci on main should not produce any modified files.

[theunrepentantgeek]

Flagged as high-priority because, while rare, when this happens it stalls all CI builds until fixed.

[theunrepentantgeek]

I believe I've identified the scenario:

• Merge a PR adding a new resource
• Our documentation index pages will not have links to the CRD docs because they haven't been generated
• Scheduled action creates a PR updating CRD docs
• Merge CRD Docs
• The branch main is now broken - when the generator is run again, the index pages will be modified to include links to the newly generated CRD documentation.

I'm testing this scenario to confirm.