feat: Added RequiredStatusCheckCommitStatus to surfaced checks enforced by branch protection

Signed-off-by: Alexei Tenitski <[email protected]>

Author: tenitski

api/v1alpha1/constants.go

@@ -19,6 +19,9 @@ const ChangeTransferPolicyLabel = "promoter.argoproj.io/change-transfer-policy"
 // TimedCommitStatusLabel the timed commit status which the commit status is associated with.
 const TimedCommitStatusLabel = "promoter.argoproj.io/timed-commit-status"
 
+// RequiredStatusCheckCommitStatusLabel identifies required status check commit statuses
+const RequiredStatusCheckCommitStatusLabel = "promoter.argoproj.io/required-status-check-commit-status"
+
 // PreviousEnvironmentCommitStatusKey the commit status key name used to indicate the previous environment health
 const PreviousEnvironmentCommitStatusKey = "promoter-previous-environment"
 

api/v1alpha1/controllerconfiguration_types.go

@@ -64,6 +64,11 @@ type ControllerConfigurationSpec struct {
 	// including WorkQueue settings that control reconciliation behavior.
 	// +required
 	GitCommitStatus GitCommitStatusConfiguration `json:"gitCommitStatus"`
+
+	// RequiredStatusCheckCommitStatus contains the configuration for the RequiredStatusCheckCommitStatus controller,
+	// including WorkQueue settings that control reconciliation behavior.
+	// +required
+	RequiredStatusCheckCommitStatus RequiredStatusCheckCommitStatusConfiguration `json:"requiredStatusCheckCommitStatus"`
 }
 
 // PromotionStrategyConfiguration defines the configuration for the PromotionStrategy controller.
@@ -156,6 +161,17 @@ type GitCommitStatusConfiguration struct {
 	WorkQueue WorkQueue `json:"workQueue"`
 }
 
+// RequiredStatusCheckCommitStatusConfiguration defines the configuration for the RequiredStatusCheckCommitStatus controller.
+//
+// This configuration controls how the RequiredStatusCheckCommitStatus controller processes reconciliation
+// requests, including requeue intervals, concurrency limits, and rate limiting behavior.
+type RequiredStatusCheckCommitStatusConfiguration struct {
+	// WorkQueue contains the work queue configuration for the RequiredStatusCheckCommitStatus controller.
+	// This includes requeue duration, maximum concurrent reconciles, and rate limiter settings.
+	// +required
+	WorkQueue WorkQueue `json:"workQueue"`
+}
+
 // WorkQueue defines the work queue configuration for a controller.
 //
 // This configuration directly correlates to parameters used with Kubernetes client-go work queues.

api/v1alpha1/promotionstrategy_types.go

@@ -53,6 +53,15 @@ type PromotionStrategySpec struct {
 	// +listMapKey=key
 	ProposedCommitStatuses []CommitStatusSelector `json:"proposedCommitStatuses"`
 
+	// ShowRequiredStatusChecks enables automatic discovery and visibility of GitHub required
+	// status checks. When enabled, the controller queries GitHub Rulesets API to discover
+	// required checks and creates CommitStatus resources for each, providing visibility into
+	// what checks are blocking PR merges. This keeps the PromotionStrategy in "progressing"
+	// state while waiting on checks, rather than "degraded" from failed merge attempts.
+	// Defaults to false.
+	// +kubebuilder:validation:Optional
+	ShowRequiredStatusChecks *bool `json:"showRequiredStatusChecks,omitempty"`
+
 	// Environments is the sequence of environments that a dry commit will be promoted through.
 	// +kubebuilder:validation:MinItems:=1
 	// +listType:=map
@@ -89,6 +98,13 @@ type Environment struct {
 	// +listType:=map
 	// +listMapKey=key
 	ProposedCommitStatuses []CommitStatusSelector `json:"proposedCommitStatuses"`
+
+	// ExcludedRequiredStatusChecks lists GitHub check contexts to exclude from
+	// visibility when showRequiredStatusChecks is enabled. These checks will still
+	// be enforced by GitHub, but won't be surfaced as CommitStatus resources.
+	// Example: ["ci-tests", "security-scan"]
+	// +kubebuilder:validation:Optional
+	ExcludedRequiredStatusChecks []string `json:"excludedRequiredStatusChecks,omitempty"`
 }
 
 // GetAutoMerge returns the value of the AutoMerge field, defaulting to true if the field is nil.
@@ -128,6 +144,14 @@ func (ps *PromotionStrategy) GetConditions() *[]metav1.Condition {
 	return &ps.Status.Conditions
 }
 
+// GetShowRequiredStatusChecks returns the value of the ShowRequiredStatusChecks field, defaulting to false if the field is nil.
+func (ps *PromotionStrategy) GetShowRequiredStatusChecks() bool {
+	if ps.Spec.ShowRequiredStatusChecks == nil {
+		return false
+	}
+	return *ps.Spec.ShowRequiredStatusChecks
+}
+
 // EnvironmentStatus defines the observed state of an environment in a PromotionStrategy.
 type EnvironmentStatus struct {
 	// Branch is the name of the active branch for the environment.

api/v1alpha1/requiredstatuscheckcommitstatus_types.go

@@ -0,0 +1,121 @@
+/*
+Copyright 2024.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// RequiredStatusCheckCommitStatusSpec defines the desired state of RequiredStatusCheckCommitStatus
+type RequiredStatusCheckCommitStatusSpec struct {
+	// PromotionStrategyRef references the PromotionStrategy that owns this controller
+	// +required
+	PromotionStrategyRef ObjectReference `json:"promotionStrategyRef"`
+}
+
+// RequiredStatusCheckCommitStatusStatus defines the observed state of RequiredStatusCheckCommitStatus
+type RequiredStatusCheckCommitStatusStatus struct {
+	// Environments contains status for each environment's branch protection checks
+	// +listType=map
+	// +listMapKey=branch
+	// +optional
+	Environments []RequiredStatusCheckEnvironmentStatus `json:"environments,omitempty"`
+
+	// Conditions represent the latest available observations of the resource's state
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// RequiredStatusCheckEnvironmentStatus defines the observed required check status for a specific environment.
+type RequiredStatusCheckEnvironmentStatus struct {
+	// Branch is the target branch being monitored
+	// +required
+	Branch string `json:"branch"`
+
+	// Sha is the commit SHA being checked
+	// +required
+	Sha string `json:"sha"`
+
+	// RequiredChecks lists all required checks discovered from GitHub Rulesets
+	// +listType=map
+	// +listMapKey=context
+	// +optional
+	RequiredChecks []RequiredCheckStatus `json:"requiredChecks,omitempty"`
+
+	// Phase is the aggregated phase of all required checks
+	// +kubebuilder:validation:Enum=pending;success;failure
+	// +required
+	Phase CommitStatusPhase `json:"phase"`
+}
+
+// RequiredCheckStatus defines the status of a single required check.
+type RequiredCheckStatus struct {
+	// Context is the GitHub check context name
+	// +required
+	Context string `json:"context"`
+
+	// Phase is the current phase of this check
+	// +kubebuilder:validation:Enum=pending;success;failure
+	// +required
+	Phase CommitStatusPhase `json:"phase"`
+
+	// CommitStatusName is the name of the CommitStatus resource created for this check
+	// +optional
+	CommitStatusName string `json:"commitStatusName,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+
+// RequiredStatusCheckCommitStatus is the Schema for the requiredstatuscheckcommitstatuses API
+// +kubebuilder:printcolumn:name="PromotionStrategy",type=string,JSONPath=`.spec.promotionStrategyRef.name`
+// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
+type RequiredStatusCheckCommitStatus struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// spec defines the desired state of RequiredStatusCheckCommitStatus
+	// +required
+	Spec RequiredStatusCheckCommitStatusSpec `json:"spec"`
+
+	// status defines the observed state of RequiredStatusCheckCommitStatus
+	// +optional
+	Status RequiredStatusCheckCommitStatusStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// RequiredStatusCheckCommitStatusList contains a list of RequiredStatusCheckCommitStatus
+type RequiredStatusCheckCommitStatusList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []RequiredStatusCheckCommitStatus `json:"items"`
+}
+
+// GetConditions returns the conditions of the RequiredStatusCheckCommitStatus.
+func (rsccs *RequiredStatusCheckCommitStatus) GetConditions() *[]metav1.Condition {
+	return &rsccs.Status.Conditions
+}
+
+func init() {
+	SchemeBuilder.Register(&RequiredStatusCheckCommitStatus{}, &RequiredStatusCheckCommitStatusList{})
+}