Additional docs on git-wait-for-pr

[snuggie12]

Checklist

• I've searched the issue queue to verify this is not a duplicate feature request.
• I've pasted the output of kargo version, if applicable.
• I've pasted logs, if applicable.

Proposed Feature

I was testing out git-wait-for-pr and after merging it seemed a few minutes had gone by and nothing had happened. Unsure if it was just a coincidence, but when I hit refresh it seemed to move forward.

It'd be nice if the docs covered this feature in detail a bit more. Things I was wondering:

• Does this (effectively) ignore the retry and timeout system?
• How often does it "retry" (i.e. the built-in retries aren't used)
• Are any of these settings configurable?
• Do webhooks change the behaviour?
• Can you manually kick off a re-check?

Motivation

Would be nice to have a better understanding of this promotion step.

[snuggie12]

Oh, I should say I've also read https://docs.kargo.io/user-guide/reference-docs/promotion-templates/#step-retries which happens to mention this step, but even that I'm confused on. What does error and retry mean in this example? Like getting a 404 on a specific PR number?

[krancour]

after merging it seemed a few minutes had gone by and nothing had happened. Unsure if it was just a coincidence, but when I hit refresh it seemed to move forward.

This is the nature of Kubernetes. Resources are reconciled by their controller when they have changed or some interval has elapsed -- whichever comes first. Merging the PR in your Git repo doesn't directly affect the Promotion state, so the Promotion is being reconciled on its usual interval.

but when I hit refresh it seemed to move forward.

This is what refresh was designed for. It changes an annotation on the Promotion to prompt immediate reconciliation of the resource.

---

Does this (effectively) ignore the retry and timeout system?

It does not, but by default there is no timeout.

"Retries" are strictly about retrying after errors. When a step such as this one effectively polls an external system on each reconciliation attempt, waiting for some condition to be satisfied, finding that condition not yet met is an anticipated likelihood and not an error. We tried to be clear on this point, but perhaps we were not.

How often does it "retry" (i.e. the built-in retries aren't used)

Retries after an error are initially almost instant, with a progressive backoff. i.e. The same way errors in any Kubernetes controller's reconciliation process are handled.

As mentioned, polling is different. It occurs at regular intervals. That's "five minutes," but not really. It can be much sooner if the resource has a state change. It can be much longer if the system is under heavy load.

Are any of these settings configurable?

If we're talking about the normal "five minute" reconciliation interval, that is currently only configurable for Warehouses. One may wish to decrease the interval on account of their polling of external systems (repositories) and wanting to notice new artifacts more quickly. One may want to increase the interval because polling for new artifacts can be "expensive" (mainly in the case of images).

There's an issue open already requesting for this to be configurable for all resource types. I'm not sure yet what we'll do about that. Most resource types wouldn't benefit much from that because most don't interact with external systems. Promotions do, but there's little reason to increase the interval and rather than decrease the interval I'd rather address the problem with webhooks, which segues into your next question...

Do webhooks change the behaviour?

Not yet. At present, webhooks only trigger reconciliation of Warehouses subscribed to the repository a push event originated from. We do not yet have merge events triggering reconciliation of a Promotion waiting on the PR the event originated from. We intend to.

Can you manually kick off a re-check?

Yes. And you did when you clicked refresh.

which happens to mention this step

This step was a very good example for timeouts because it's quite likely you may want to give up on a Promotion if a PR its waiting on has gone unmerged for a very long period of time.

It turns out to be a very poor example of error thresholds for the very reason that periodic polling of PR status is different than a retry and those completely separate behaviors are too easily being confused.

We will split demonstration of timeouts and error thresholds into two separate examples with the latter using a different step in order to avoid this confusion.

What does error and retry mean in this example?

Any actual error.

---

I hope this helps and we'll make slight adjustments to the docs as soon as is feasbile.

[snuggie12]

@krancour, very helpful and I agree with your assessment of things on what could be adjusted. Thanks!