feat(health): finalizer messages for Promoter checks

Author: crenshaw-dev

resource_customizations/promoter.argoproj.io/ArgoCDCommitStatus/health.lua

@@ -1,3 +1,5 @@
+-- CRD spec: https://gitops-promoter.readthedocs.io/en/latest/crd-specs/#argocdcommitstatus
+
 local hs = {}
 hs.status = "Progressing"
 hs.message = "Initializing Argo CD commit status"

resource_customizations/promoter.argoproj.io/ChangeTransferPolicy/health.lua

@@ -1,11 +1,37 @@
+-- CRD spec: https://gitops-promoter.readthedocs.io/en/latest/crd-specs/#changetransferpolicy
+-- Promoter finalizers: https://gitops-promoter.readthedocs.io/en/latest/debugging/finalizers/
+
+local function formatDeletingWithFinalizers(base, finalizers, catalog)
+    if not finalizers then
+        return base
+    end
+    local parts = { base }
+    for _, f in ipairs(finalizers) do
+        local e = catalog[f]
+        if e then
+            table.insert(parts, f .. ": " .. e.wait .. " Risk if removed manually: " .. e.risk)
+        end
+    end
+    return table.concat(parts, " ")
+end
+
 local hs = {}
 hs.status = "Progressing"
 hs.message = "Initializing change transfer policy"
 
 -- Check for deletion timestamp
 if obj.metadata.deletionTimestamp then
     hs.status = "Progressing"
-    hs.message = "Change transfer policy is being deleted"
+    hs.message = formatDeletingWithFinalizers(
+        "Change transfer policy is being deleted.",
+        obj.metadata.finalizers,
+        {
+            ["changetransferpolicy.promoter.argoproj.io/finalizer"] = {
+                wait = "Waiting to clear related PullRequest finalizers and finish cleanup before this policy is removed.",
+                risk = "the policy can disappear while related PullRequests are still terminating or inconsistent with Git.",
+            },
+        }
+    )
     return hs
 end
 

resource_customizations/promoter.argoproj.io/ChangeTransferPolicy/health_test.yaml

@@ -5,7 +5,7 @@ tests:
   inputPath: testdata/no-status.yaml
 - healthStatus:
     status: Progressing
-    message: Change transfer policy is being deleted
+    message: 'Change transfer policy is being deleted. changetransferpolicy.promoter.argoproj.io/finalizer: Waiting to clear related PullRequest finalizers and finish cleanup before this policy is removed. Risk if removed manually: the policy can disappear while related PullRequests are still terminating or inconsistent with Git.'
   inputPath: testdata/deleting.yaml
 - healthStatus:
     status: Progressing

resource_customizations/promoter.argoproj.io/ChangeTransferPolicy/testdata/deleting.yaml

@@ -3,3 +3,5 @@ kind: ChangeTransferPolicy
 metadata:
   name: test
   deletionTimestamp: "2025-07-04T12:00:00Z"
+  finalizers:
+    - changetransferpolicy.promoter.argoproj.io/finalizer

resource_customizations/promoter.argoproj.io/ClusterScmProvider/health.lua

@@ -1,3 +1,20 @@
+-- CRD spec: https://gitops-promoter.readthedocs.io/en/latest/crd-specs/#clusterscmprovider
+-- Promoter finalizers: https://gitops-promoter.readthedocs.io/en/latest/debugging/finalizers/
+
+local function formatDeletingWithFinalizers(base, finalizers, catalog)
+    if not finalizers then
+        return base
+    end
+    local parts = { base }
+    for _, f in ipairs(finalizers) do
+        local e = catalog[f]
+        if e then
+            table.insert(parts, f .. ": " .. e.wait .. " Risk if removed manually: " .. e.risk)
+        end
+    end
+    return table.concat(parts, " ")
+end
+
 local hs = {}
 hs.status = "Progressing"
 hs.message = "Initializing cluster SCM provider"
@@ -6,7 +23,16 @@ hs.message = "Initializing cluster SCM provider"
 
 if obj.metadata.deletionTimestamp then
     hs.status = "Progressing"
-    hs.message = "ClusterScmProvider is being deleted"
+    hs.message = formatDeletingWithFinalizers(
+        "ClusterScmProvider is being deleted.",
+        obj.metadata.finalizers,
+        {
+            ["clusterscmprovider.promoter.argoproj.io/finalizer"] = {
+                wait = "Waiting until no GitRepository still references this cluster-wide SCM provider.",
+                risk = "GitRepository objects can reference a provider that no longer exists.",
+            },
+        }
+    )
     return hs
 end
 

resource_customizations/promoter.argoproj.io/ClusterScmProvider/health_test.yaml

@@ -5,7 +5,7 @@ tests:
   inputPath: testdata/no-status.yaml
 - healthStatus:
     status: Progressing
-    message: ClusterScmProvider is being deleted
+    message: 'ClusterScmProvider is being deleted. clusterscmprovider.promoter.argoproj.io/finalizer: Waiting until no GitRepository still references this cluster-wide SCM provider. Risk if removed manually: GitRepository objects can reference a provider that no longer exists.'
   inputPath: testdata/deleting.yaml
 - healthStatus:
     status: Progressing

resource_customizations/promoter.argoproj.io/ClusterScmProvider/testdata/deleting.yaml

@@ -3,6 +3,8 @@ kind: ClusterScmProvider
 metadata:
   name: github-enterprise
   deletionTimestamp: "2025-07-04T12:00:00Z"
+  finalizers:
+    - clusterscmprovider.promoter.argoproj.io/finalizer
 spec:
   secretRef:
     name: github-app-secret

resource_customizations/promoter.argoproj.io/CommitStatus/health.lua

@@ -1,3 +1,5 @@
+-- CRD spec: https://gitops-promoter.readthedocs.io/en/latest/crd-specs/#commitstatus
+
 local hs = {}
 hs.status = "Progressing"
 hs.message = "Initializing commit status"

resource_customizations/promoter.argoproj.io/GitCommitStatus/health.lua

@@ -1,3 +1,5 @@
+-- CRD spec: https://gitops-promoter.readthedocs.io/en/latest/crd-specs/
+
 local hs = {}
 hs.status = "Progressing"
 hs.message = "Initializing git commit validation"

resource_customizations/promoter.argoproj.io/GitRepository/health.lua

@@ -1,3 +1,20 @@
+-- CRD spec: https://gitops-promoter.readthedocs.io/en/latest/crd-specs/#gitrepository
+-- Promoter finalizers: https://gitops-promoter.readthedocs.io/en/latest/debugging/finalizers/
+
+local function formatDeletingWithFinalizers(base, finalizers, catalog)
+    if not finalizers then
+        return base
+    end
+    local parts = { base }
+    for _, f in ipairs(finalizers) do
+        local e = catalog[f]
+        if e then
+            table.insert(parts, f .. ": " .. e.wait .. " Risk if removed manually: " .. e.risk)
+        end
+    end
+    return table.concat(parts, " ")
+end
+
 local hs = {}
 hs.status = "Progressing"
 hs.message = "Initializing Git repository"
@@ -6,7 +23,16 @@ hs.message = "Initializing Git repository"
 
 if obj.metadata.deletionTimestamp then
     hs.status = "Progressing"
-    hs.message = "GitRepository is being deleted"
+    hs.message = formatDeletingWithFinalizers(
+        "GitRepository is being deleted.",
+        obj.metadata.finalizers,
+        {
+            ["gitrepository.promoter.argoproj.io/finalizer"] = {
+                wait = "Waiting until no non-deleting PullRequests still reference this repository.",
+                risk = "repository metadata may be removed while promotions still depend on it.",
+            },
+        }
+    )
     return hs
 end