fix: Annotate PLR when when started status is reported (openshift-pipelines#2208)

* fix: Annotate PLR when started status is reported

The use of the state label (which is mutable) for deciding when to report
to the SCM that the PLR was started is flaky.

It was seen that the reconciler get events about PLRs with unexpected
value for the state label. For example, after the status is reported
to the SCM, and the label value is patched to "started", after serval
reconcile iterations the label had the "queued" value again. This can
happen because of unsafe patching done by controllers
(not just the PAC controllers) which reconciles PLRs.

Introduce a new annotation for indicating the the status was reported
to the SCM. By adding an annotation which is set once, we remove the
risk that its value will get overwritten by other controllers
(since maps are merged when patched, values are not getting removed
unless explicitly defined in the patch
- https://datatracker.ietf.org/doc/html/rfc7386#section-2)

In addition, at the start of each reconcile loop, ensure that we
operate on the latest version of the PLR and not using a stale value
from the cache.

Assisted-By: Cursor
Signed-off-by: Gal Ben Haim <[email protected]>

Author: gbenhaim

README.md

@@ -14,6 +14,8 @@ from your source code repository.
 
 ---
 
+Why are you adding this line?
+
 ## 🚀 Introduction
 
 Pipelines-as-Code follows the [Pipelines-as-Code

pkg/pipelineascode/pipelineascode.go

@@ -310,6 +310,11 @@ func getMergePatch(annotations, labels map[string]string) map[string]any {
 	}
 }
 
+// getExecutionOrderPatch returns a patch to set the execution order of the pipelineRun
+// the order is a comma separated list of pipelineRun names
+// the order is used to determine the order in which the pipelineRuns are executed
+// the order is set in the metadata.annotations.execution-order annotation
+// the order is used to determine the order in which the pipelineRuns are executed.
 func getExecutionOrderPatch(order string) map[string]any {
 	return map[string]any{
 		"metadata": map[string]any{