feat!: GitOps Reverser decides when Flux or Argo CD applies a folder

.coverage-baseline

@@ -1 +1 @@
-79.9
+80.0

.docs-lint-scope

@@ -25,6 +25,8 @@
 README.md
 docs/architecture.md
 docs/configuration.md
+docs/flux.md
+docs/argocd.md
 docs/spec/attribution.md
 docs/components.md
 docs/quickstart.md

api/v1alpha3/gitprovider_types.go

@@ -3,6 +3,10 @@
 package v1alpha3
 
 import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+
 	meta "github.com/fluxcd/pkg/apis/meta"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
@@ -54,6 +58,68 @@ type GitProviderSpec struct {
 	// formatting moved to GitTarget.spec.commit.message.
 	// +optional
 	Commit *CommitSpec `json:"commit,omitempty"`
+
+	// The names are Flux's Receiver's, type values included, so a Flux user already knows them.
+
+	// Receiver lets the Git host tell GitOps Reverser that somebody pushed. Point the host's push
+	// webhook at the receiver listener plus status.webhookPath, with the Secret's token as the
+	// webhook secret. A delivery is only a hint: it makes GitOps Reverser read where the branch is
+	// on the remote, and what the remote says decides whether a GitTarget's applier is asked to
+	// apply. Without a receiver, a foreign push is still found, by the next rejected push or by
+	// the periodic refresh.
+	// +optional
+	Receiver *GitProviderReceiver `json:"receiver,omitempty"`
+}
+
+// GitProviderReceiver is the push-notification endpoint of a GitProvider.
+type GitProviderReceiver struct {
+	// Type is the payload and signature the Git host sends. "github" checks X-Hub-Signature-256,
+	// "gitlab" checks X-Gitlab-Token, "gitea" checks X-Gitea-Signature, and "generic-hmac" checks
+	// X-Signature: sha256=<hex HMAC of the body> over a {"repository", "branch", "after"} body,
+	// for a relay of your own.
+	// +required
+	// +kubebuilder:validation:Enum=github;gitlab;gitea;generic-hmac
+	Type ReceiverType `json:"type"`
+
+	// SecretRef names a Secret in this namespace whose "token" key is the webhook secret. The
+	// token also derives status.webhookPath, so rotating it moves the path: register the new path
+	// with the new secret.
+	// +required
+	SecretRef meta.LocalObjectReference `json:"secretRef"`
+}
+
+// ReceiverType is the payload format a receiver accepts. The values are Flux's Receiver types.
+type ReceiverType string
+
+const (
+	// ReceiverTypeGitHub is a GitHub push event.
+	ReceiverTypeGitHub ReceiverType = "github"
+	// ReceiverTypeGitLab is a GitLab push event.
+	ReceiverTypeGitLab ReceiverType = "gitlab"
+	// ReceiverTypeGitea is a Gitea push event.
+	ReceiverTypeGitea ReceiverType = "gitea"
+	// ReceiverTypeGenericHMAC is a {"repository", "branch", "after"} body signed as Flux's
+	// generic-hmac Receiver expects.
+	ReceiverTypeGenericHMAC ReceiverType = "generic-hmac"
+)
+
+// ReceiverTokenKey is the Secret key holding a receiver's token, the key a Flux Receiver Secret uses.
+const ReceiverTokenKey = "token"
+
+// ReceiverPathPrefix is the prefix every receiver path starts with.
+const ReceiverPathPrefix = "/git-push/"
+
+// A path that names the GitProvider would let anybody who can reach the listener list which
+// namespaces and providers exist. Like Flux's Receiver, the path is derived from the token, so
+// only whoever holds the token can find it; unlike Flux's sha256(token+name+namespace), it is an
+// HMAC over "namespace/name", which no two providers sharing a token can collide on.
+
+// ReceiverPath is the path a GitProvider's receiver is served on: the prefix and the hex
+// HMAC-SHA256 of "<namespace>/<name>", keyed by the receiver token.
+func ReceiverPath(token []byte, namespace, name string) string {
+	mac := hmac.New(sha256.New, token)
+	mac.Write([]byte(namespace + "/" + name))
+	return ReceiverPathPrefix + hex.EncodeToString(mac.Sum(nil))
 }
 
 // KnownHostsReference points at a namespace-local ConfigMap or Secret that holds SSH known_hosts
@@ -166,6 +232,12 @@ type GitProviderStatus struct {
 	// that cadence. Providers are few and the check was already running; this adds no request.
 	// +optional
 	LastVerifiedAt *metav1.Time `json:"lastVerifiedAt,omitempty"`
+
+	// WebhookPath is the path spec.receiver is served on, under the receiver listener:
+	// /git-push/ and a hash of this provider's name and the receiver token. Empty without
+	// spec.receiver, and while the token Secret or its "token" key is missing.
+	// +optional
+	WebhookPath string `json:"webhookPath,omitempty"`
 }
 
 // GitProviderBranchStatus is one branch of this repository that GitTargets are configured to

api/v1alpha3/helpers_test.go

@@ -321,3 +321,21 @@ func TestIsLocalSource_IsANameTest(t *testing.T) {
 		})
 	}
 }
+
+// TestApplierCluster_DefaultsToTheSourceCluster: an omitted spec.applier.clusterProviderRef is the
+// GitTarget's own source cluster, never the "default" provider, so a remote-source target keeps its
+// meaning when the field is added to the API.
+func TestApplierCluster_DefaultsToTheSourceCluster(t *testing.T) {
+	target := &GitTarget{Spec: GitTargetSpec{
+		ClusterProviderRef: &meta.LocalObjectReference{Name: "prod-eu-1"},
+		Applier:            &GitTargetApplier{},
+	}}
+	assert.Equal(t, "prod-eu-1", target.ApplierCluster())
+
+	target.Spec.Applier.ClusterProviderRef = &meta.LocalObjectReference{Name: "hub"}
+	assert.Equal(t, "hub", target.ApplierCluster())
+
+	target.Spec.ClusterProviderRef = nil
+	target.Spec.Applier.ClusterProviderRef = nil
+	assert.Equal(t, DefaultClusterProviderName, target.ApplierCluster())
+}

charts/gitops-reverser/README.md

@@ -180,6 +180,9 @@ nodeSelector:
 | `controllerManager.branchBufferMaxSize` | Maximum in-memory event buffer per branch worker. Bounds the open commit window plus the writes retained for replay until a push succeeds. While the remote cannot be reached, retained writes that reach it close the worker to new writes, saves and resyncs until they are published; the watch delivers a refused event again | `8Mi` |
 | `controllerManager.commitRequestTTL` | How long a `CommitRequest` is kept once it finishes. Written onto the request as the `configbutler.ai/delete-after` annotation; remove or edit that to keep one. `"0"` writes none | `48h` |
 | `git.refreshInterval` | How often an idle `GitTarget` re-proves where its branch is on the Git remote. `"0"` disables it | `10m` |
+| `receiver.bindAddress` | `host:port` the push receiver listens on, over plain HTTP (`--receiver-bind-address`), for Git hosts' push webhooks to `GitProvider.status.webhookPath`. Empty or `"0"` serves no receiver. When set, the chart adds a `<release>-receiver` Service; expose it with an Ingress or Gateway route of your own that terminates TLS. See [push receiver settings](../../docs/configuration.md#push-receiver-settings) | `""` |
+| `applierAccess.flux` | Grant the operator `get` and `patch` on Flux `Kustomizations` and `GitRepositories`, and `create` on `SelfSubjectAccessReviews`, so it can ask Flux to apply a commit somebody else pushed | `false` |
+| `applierAccess.argocd` | Grant the operator `get` and `update` on Argo CD `Applications`, and `create` on `SelfSubjectAccessReviews`, so it can start the syncs of an `Application` named by `spec.applier.applicationRef` | `false` |
 | `auditService.type` | Service type for the dedicated audit Service | `NodePort` |
 | `auditService.nodePort` | Fixed NodePort for the audit Service when `auditService.type=NodePort` | `30444` |
 | `auditService.clusterIP` | Optional fixed ClusterIP for the dedicated audit Service | `""` |
@@ -220,6 +223,7 @@ nodeSelector:
 | `servers.metrics.tls.secretNameOverride` | Override Secret name for metrics TLS cert/key | `<release>-metrics-server-cert` |
 | `service.clusterIP` | Optional fixed ClusterIP for single controller Service | `""` |
 | `service.ports.audit` | Service port for audit ingress when `attribution.enabled=true` | `9444` |
+| `service.ports.receiver` | Port of the `<release>-receiver` Service when `receiver.bindAddress` is set | `80` |
 | `service.ports.metrics` | Service port for metrics | `8080` |
 | `servers.healthProbe.bindAddress` | Liveness/readiness probe bind address (`--health-probe-bind-address`) | `:8081` |
 | `servers.admission.port` | Admission webhook container/Service port | `9443` |

charts/gitops-reverser/templates/_helpers.tpl

@@ -107,3 +107,27 @@ as the Certificate name and in the webhook's cert-manager.io/inject-ca-from anno
 {{- define "gitops-reverser.admissionServerCertName" -}}
 {{- printf "%s-admission-server-cert" (include "gitops-reverser.fullname" .) -}}
 {{- end }}
+
+{{/*
+Non-empty when the push receiver listener is on: receiver.bindAddress is set and is not the "0"
+the binary reads as off. Used as `if include ...`, so it renders "true" or nothing.
+*/}}
+{{- define "gitops-reverser.receiverEnabled" -}}
+{{- $addr := .Values.receiver.bindAddress | default "" | toString | trim -}}
+{{- if and $addr (ne $addr "0") -}}true{{- end -}}
+{{- end }}
+
+{{/*
+The port in receiver.bindAddress ("host:port"; an empty host or an IPv6 "[::]" host included), so
+the containerPort and the Service's targetPort cannot drift from what the binary binds.
+*/}}
+{{- define "gitops-reverser.receiverPort" -}}
+{{- splitList ":" (.Values.receiver.bindAddress | toString | trim) | last | int -}}
+{{- end }}
+
+{{/*
+Name of the push receiver Service.
+*/}}
+{{- define "gitops-reverser.receiverServiceName" -}}
+{{- printf "%s-receiver" (include "gitops-reverser.fullname" .) | trunc 63 | trimSuffix "-" }}
+{{- end }}

charts/gitops-reverser/templates/applier-rbac.yaml

@@ -0,0 +1,93 @@
+{{- if and .Values.rbac.create .Values.applierAccess.flux }}
+# What GitOps Reverser needs to ask Flux to apply a commit after somebody else pushed to a branch a
+# GitTarget writes: read and patch the Kustomization and its GitRepository (an apply request is a
+# reconcile request on them), and create SelfSubjectAccessReviews so the operator can check it holds
+# that access before relying on it. Separate from the manager role because it is optional and
+# names another project's API: an install without Flux grants nothing on it. See
+# docs/design/apply-trigger.md.
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "gitops-reverser.fullname" . }}-applier-flux
+  labels:
+    {{- include "gitops-reverser.labels" . | nindent 4 }}
+rules:
+- apiGroups:
+  - kustomize.toolkit.fluxcd.io
+  resources:
+  - kustomizations
+  verbs:
+  - get
+  - patch
+- apiGroups:
+  - source.toolkit.fluxcd.io
+  resources:
+  - gitrepositories
+  verbs:
+  - get
+  - patch
+- apiGroups:
+  - authorization.k8s.io
+  resources:
+  - selfsubjectaccessreviews
+  verbs:
+  - create
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: {{ include "gitops-reverser.fullname" . }}-applier-flux
+  labels:
+    {{- include "gitops-reverser.labels" . | nindent 4 }}
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: {{ include "gitops-reverser.fullname" . }}-applier-flux
+subjects:
+- kind: ServiceAccount
+  name: {{ include "gitops-reverser.serviceAccountName" . }}
+  namespace: {{ .Release.Namespace }}
+{{- end }}
+{{- if and .Values.rbac.create .Values.applierAccess.argocd }}
+---
+# What GitOps Reverser needs to ask an Argo CD Application to sync a commit it checked: read the
+# Application and update it with a sync operation (how Argo CD's own automated sync starts one), and
+# create SelfSubjectAccessReviews so the operator can check it holds that access before relying on
+# it. Separate from the manager role because it is optional and names another project's API: an
+# install without Argo CD grants nothing on it. See docs/argocd.md.
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "gitops-reverser.fullname" . }}-applier-argocd
+  labels:
+    {{- include "gitops-reverser.labels" . | nindent 4 }}
+rules:
+- apiGroups:
+  - argoproj.io
+  resources:
+  - applications
+  verbs:
+  - get
+  - update
+- apiGroups:
+  - authorization.k8s.io
+  resources:
+  - selfsubjectaccessreviews
+  verbs:
+  - create
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: {{ include "gitops-reverser.fullname" . }}-applier-argocd
+  labels:
+    {{- include "gitops-reverser.labels" . | nindent 4 }}
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: {{ include "gitops-reverser.fullname" . }}-applier-argocd
+subjects:
+- kind: ServiceAccount
+  name: {{ include "gitops-reverser.serviceAccountName" . }}
+  namespace: {{ .Release.Namespace }}
+{{- end }}