feat: ESO integration + change default projects path to apps/

patrickleet · claude · patrickleet · commit 69b5b1d38615 · 2026-04-04T18:15:51.000-05:00
ESO integration for ArgoCD repo credentials:
- ExternalSecret pulls GitHub App creds from AWS Secrets Manager
- Projects/Crossplane apps gated on repo creds when ESO enabled
- Usage protects deletion ordering
- 5 new unit tests (17 total, all passing)

DX improvements:
- Default projects.path changed from .gitops/deploy to apps/
- Works with hops-ops/gitops-template for intuitive repo structure

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/on-pr.yaml b/.github/workflows/on-pr.yaml
@@ -34,7 +34,11 @@ jobs:
           { "example": "examples/gitopsstacks/minimal.yaml" },
           { "example": "examples/gitopsstacks/standard.yaml" },
           { "example": "examples/gitopsstacks/standard.yaml", "observed_resources": "examples/test/mocks/observed-resources/standard/steps/1/" },
-          { "example": "examples/gitopsstacks/standard.yaml", "observed_resources": "examples/test/mocks/observed-resources/standard/steps/2/" }
+          { "example": "examples/gitopsstacks/standard.yaml", "observed_resources": "examples/test/mocks/observed-resources/standard/steps/2/" },
+          { "example": "examples/gitopsstacks/eso.yaml" },
+          { "example": "examples/gitopsstacks/eso.yaml", "observed_resources": "examples/test/mocks/observed-resources/eso/steps/1/" },
+          { "example": "examples/gitopsstacks/eso.yaml", "observed_resources": "examples/test/mocks/observed-resources/eso/steps/2/" },
+          { "example": "examples/gitopsstacks/eso.yaml", "observed_resources": "examples/test/mocks/observed-resources/eso/steps/3/" }
         ]
       api_path: apis/gitopsstacks
       error_on_missing_schemas: true
diff --git a/.github/workflows/on-push-main.yaml b/.github/workflows/on-push-main.yaml
@@ -30,7 +30,11 @@ jobs:
           { "example": "examples/gitopsstacks/minimal.yaml" },
           { "example": "examples/gitopsstacks/standard.yaml" },
           { "example": "examples/gitopsstacks/standard.yaml", "observed_resources": "examples/test/mocks/observed-resources/standard/steps/1/" },
-          { "example": "examples/gitopsstacks/standard.yaml", "observed_resources": "examples/test/mocks/observed-resources/standard/steps/2/" }
+          { "example": "examples/gitopsstacks/standard.yaml", "observed_resources": "examples/test/mocks/observed-resources/standard/steps/2/" },
+          { "example": "examples/gitopsstacks/eso.yaml" },
+          { "example": "examples/gitopsstacks/eso.yaml", "observed_resources": "examples/test/mocks/observed-resources/eso/steps/1/" },
+          { "example": "examples/gitopsstacks/eso.yaml", "observed_resources": "examples/test/mocks/observed-resources/eso/steps/2/" },
+          { "example": "examples/gitopsstacks/eso.yaml", "observed_resources": "examples/test/mocks/observed-resources/eso/steps/3/" }
         ]
       api_path: apis/gitopsstacks
       error_on_missing_schemas: true
diff --git a/Makefile b/Makefile
@@ -21,7 +21,11 @@ EXAMPLES := \
     examples/gitopsstacks/minimal.yaml:: \
     examples/gitopsstacks/standard.yaml:: \
     examples/gitopsstacks/standard.yaml::examples/test/mocks/observed-resources/standard/steps/1/ \
-    examples/gitopsstacks/standard.yaml::examples/test/mocks/observed-resources/standard/steps/2/
+    examples/gitopsstacks/standard.yaml::examples/test/mocks/observed-resources/standard/steps/2/ \
+    examples/gitopsstacks/eso.yaml:: \
+    examples/gitopsstacks/eso.yaml::examples/test/mocks/observed-resources/eso/steps/1/ \
+    examples/gitopsstacks/eso.yaml::examples/test/mocks/observed-resources/eso/steps/2/ \
+    examples/gitopsstacks/eso.yaml::examples/test/mocks/observed-resources/eso/steps/3/
 
 # Render all examples (parallel execution, output shown per-job when complete)
 render\:all:
diff --git a/apis/gitopsstacks/definition.yaml b/apis/gitopsstacks/definition.yaml
@@ -140,6 +140,34 @@ spec:
                     type: boolean
                 required:
                 - org
+              externalSecrets:
+                description: External Secrets Operator integration for ArgoCD repository credentials. Requires SecretStack as a prerequisite.
+                type: object
+                properties:
+                  enabled:
+                    description: Enable ESO integration. Creates an ExternalSecret to pull GitHub App credentials from AWS Secrets Manager into ArgoCD repo-creds.
+                    type: boolean
+                  secretStoreName:
+                    description: Name of the ClusterSecretStore created by SecretStack. Defaults to "default".
+                    type: string
+                  githubApp:
+                    description: GitHub App credential references in AWS Secrets Manager.
+                    type: object
+                    properties:
+                      secretPath:
+                        description: AWS Secrets Manager secret name containing GitHub App credentials.
+                        type: string
+                      appIdKey:
+                        description: JSON key for the GitHub App ID within the secret. Defaults to "appId".
+                        type: string
+                      installationIdKey:
+                        description: JSON key for the GitHub App Installation ID within the secret. Defaults to "installationId".
+                        type: string
+                      privateKeyKey:
+                        description: JSON key for the GitHub App private key within the secret. Defaults to "privateKey".
+                        type: string
+                    required:
+                    - secretPath
               applications:
                 description: ArgoCD Application configuration.
                 type: object
@@ -152,7 +180,7 @@ spec:
                         description: Enable the projects Application. Defaults to true.
                         type: boolean
                       path:
-                        description: Path in the gitops repo to sync. Defaults to .gitops/deploy.
+                        description: Path in the gitops repo to sync. Defaults to apps.
                         type: string
                   crossplane:
                     description: Crossplane-specific ArgoCD projects and applications.
diff --git a/examples/gitopsstacks/eso.yaml b/examples/gitopsstacks/eso.yaml
@@ -0,0 +1,26 @@
+apiVersion: hops.ops.com.ai/v1alpha1
+kind: GitopsStack
+metadata:
+  name: gitops
+  namespace: example-env
+spec:
+  clusterName: example-cluster
+  labels:
+    team: platform
+  repository:
+    org: hops-ops
+    name: example-cluster-gitops
+    description: GitOps repository for example-cluster
+    visibility: private
+  externalSecrets:
+    enabled: true
+    secretStoreName: default
+    githubApp:
+      secretPath: github/argocd-credentials
+      appIdKey: appId
+      installationIdKey: installationId
+      privateKeyKey: privateKey
+  applications:
+    projects:
+      enabled: true
+      path: .gitops/deploy
diff --git a/examples/test/mocks/observed-resources/eso/steps/1/github-repository.yaml b/examples/test/mocks/observed-resources/eso/steps/1/github-repository.yaml
@@ -0,0 +1,15 @@
+apiVersion: repo.github.m.upbound.io/v1alpha1
+kind: Repository
+metadata:
+  name: gitops-gitops-repo
+  annotations:
+    crossplane.io/composition-resource-name: github-repository
+status:
+  conditions:
+  - type: Ready
+    status: "True"
+  - type: Synced
+    status: "True"
+  atProvider:
+    fullName: hops-ops/example-cluster-gitops
+    htmlUrl: https://github.com/hops-ops/example-cluster-gitops
diff --git a/examples/test/mocks/observed-resources/eso/steps/1/helm-release-argocd.yaml b/examples/test/mocks/observed-resources/eso/steps/1/helm-release-argocd.yaml
@@ -0,0 +1,15 @@
+apiVersion: helm.m.crossplane.io/v1beta1
+kind: Release
+metadata:
+  name: argocd
+  annotations:
+    crossplane.io/composition-resource-name: helm-release-argocd
+status:
+  conditions:
+  - type: Ready
+    status: "True"
+  - type: Synced
+    status: "True"
+  atProvider:
+    state: deployed
+    revision: "1"
diff --git a/examples/test/mocks/observed-resources/eso/steps/2/external-secret-argocd-repo-creds.yaml b/examples/test/mocks/observed-resources/eso/steps/2/external-secret-argocd-repo-creds.yaml
@@ -0,0 +1,12 @@
+apiVersion: kubernetes.m.crossplane.io/v1alpha1
+kind: Object
+metadata:
+  name: gitops-argocd-repo-creds
+  annotations:
+    crossplane.io/composition-resource-name: external-secret-argocd-repo-creds
+status:
+  conditions:
+  - type: Ready
+    status: "True"
+  - type: Synced
+    status: "True"
diff --git a/examples/test/mocks/observed-resources/eso/steps/2/github-repository.yaml b/examples/test/mocks/observed-resources/eso/steps/2/github-repository.yaml
@@ -0,0 +1 @@
+../1/github-repository.yaml
diff --git a/examples/test/mocks/observed-resources/eso/steps/2/helm-release-argocd.yaml b/examples/test/mocks/observed-resources/eso/steps/2/helm-release-argocd.yaml
@@ -0,0 +1 @@
+../1/helm-release-argocd.yaml
diff --git a/examples/test/mocks/observed-resources/eso/steps/3/argocd-projects-app.yaml b/examples/test/mocks/observed-resources/eso/steps/3/argocd-projects-app.yaml
@@ -0,0 +1,12 @@
+apiVersion: kubernetes.m.crossplane.io/v1alpha1
+kind: Object
+metadata:
+  name: gitops-argocd-projects-app
+  annotations:
+    crossplane.io/composition-resource-name: argocd-projects-app
+status:
+  conditions:
+  - type: Ready
+    status: "True"
+  - type: Synced
+    status: "True"
diff --git a/examples/test/mocks/observed-resources/eso/steps/3/external-secret-argocd-repo-creds.yaml b/examples/test/mocks/observed-resources/eso/steps/3/external-secret-argocd-repo-creds.yaml
@@ -0,0 +1 @@
+../2/external-secret-argocd-repo-creds.yaml
diff --git a/examples/test/mocks/observed-resources/eso/steps/3/github-repository.yaml b/examples/test/mocks/observed-resources/eso/steps/3/github-repository.yaml
@@ -0,0 +1 @@
+../1/github-repository.yaml
diff --git a/examples/test/mocks/observed-resources/eso/steps/3/helm-release-argocd.yaml b/examples/test/mocks/observed-resources/eso/steps/3/helm-release-argocd.yaml
@@ -0,0 +1 @@
+../1/helm-release-argocd.yaml
diff --git a/functions/render/000-state-init.yaml.gotmpl b/functions/render/000-state-init.yaml.gotmpl
@@ -59,6 +59,12 @@
 # Template config (optional)
 {{- $repoTemplate := $repoSpec.template | default dict }}
 
+# ==============================================================================
+# External Secrets configuration
+# ==============================================================================
+{{- $esoSpec := $spec.externalSecrets | default dict }}
+{{- $ghAppSpec := $esoSpec.githubApp | default dict }}
+
 # ==============================================================================
 # Applications configuration
 # ==============================================================================
@@ -95,10 +101,20 @@
     "deleteBranchOnMerge" ($repoSpec.deleteBranchOnMerge | default true)
     "url" $repoUrl
   )
+  "externalSecrets" (dict
+    "enabled" ($esoSpec.enabled | default false)
+    "secretStoreName" ($esoSpec.secretStoreName | default "default")
+    "githubApp" (dict
+      "secretPath" ($ghAppSpec.secretPath | default "")
+      "appIdKey" ($ghAppSpec.appIdKey | default "appId")
+      "installationIdKey" ($ghAppSpec.installationIdKey | default "installationId")
+      "privateKeyKey" ($ghAppSpec.privateKeyKey | default "privateKey")
+    )
+  )
   "applications" (dict
     "projects" (dict
       "enabled" ($projectsSpec.enabled | default true)
-      "path" ($projectsSpec.path | default ".gitops/deploy")
+      "path" ($projectsSpec.path | default "apps")
     )
     "crossplane" (dict
       "enabled" ($crossplaneSpec.enabled | default false)
diff --git a/functions/render/010-state-status.yaml.gotmpl b/functions/render/010-state-status.yaml.gotmpl
@@ -10,7 +10,7 @@
 # ==============================================================================
 
 {{- $checkReady := dict }}
-{{- range $key := list "helm-release-argocd" "github-repository" "argocd-projects-app" "crossplane-app-project" "crossplane-configs-app" "crossplane-provider-configs-app" }}
+{{- range $key := list "helm-release-argocd" "github-repository" "argocd-projects-app" "crossplane-app-project" "crossplane-configs-app" "crossplane-provider-configs-app" "external-secret-argocd-repo-creds" }}
   {{- $entry := get $observed $key | default dict }}
   {{- $resource := $entry.resource | default dict }}
   {{- $status := $resource.status | default dict }}
@@ -43,6 +43,7 @@
     "ready" (get $checkReady "github-repository")
     "url" $observedRepoUrl
   )
+  "repoCreds" (dict "ready" (get $checkReady "external-secret-argocd-repo-creds"))
   "projectsApp" (dict "ready" (get $checkReady "argocd-projects-app"))
   "crossplaneProject" (dict "ready" (get $checkReady "crossplane-app-project"))
   "crossplaneConfigs" (dict "ready" (get $checkReady "crossplane-configs-app"))
diff --git a/functions/render/220-argocd-projects-app.yaml.gotmpl b/functions/render/220-argocd-projects-app.yaml.gotmpl
@@ -10,7 +10,12 @@
 {{- $apps := $state.applications }}
 {{- $repo := $state.repository }}
 
-{{- if and $apps.projects.enabled $obs.argocd.ready }}
+{{- $repoCredsReady := true }}
+{{- if $state.externalSecrets.enabled }}
+  {{- $repoCredsReady = $obs.repoCreds.ready }}
+{{- end }}
+
+{{- if and $apps.projects.enabled $obs.argocd.ready $repoCredsReady }}
 ---
 apiVersion: kubernetes.m.crossplane.io/v1alpha1
 kind: Object
diff --git a/functions/render/230-argocd-crossplane-apps.yaml.gotmpl b/functions/render/230-argocd-crossplane-apps.yaml.gotmpl
@@ -10,7 +10,12 @@
 {{- $apps := $state.applications }}
 {{- $repo := $state.repository }}
 
-{{- if and $apps.crossplane.enabled $obs.argocd.ready }}
+{{- $repoCredsReady := true }}
+{{- if $state.externalSecrets.enabled }}
+  {{- $repoCredsReady = $obs.repoCreds.ready }}
+{{- end }}
+
+{{- if and $apps.crossplane.enabled $obs.argocd.ready $repoCredsReady }}
 
 ---
 apiVersion: kubernetes.m.crossplane.io/v1alpha1
diff --git a/functions/render/240-external-secret-argocd-repo.yaml.gotmpl b/functions/render/240-external-secret-argocd-repo.yaml.gotmpl
@@ -0,0 +1,92 @@
+# code: language=yaml
+#
+# ExternalSecret: ArgoCD repository credentials via GitHub App
+#
+# Creates an ExternalSecret that pulls GitHub App credentials from
+# AWS Secrets Manager and creates an ArgoCD repo-creds Secret.
+# Gated on: externalSecrets.enabled AND argocd ready (namespace must exist)
+#
+# Prerequisite: SecretStack must be installed (provides ESO + ClusterSecretStore)
+#
+
+{{- $eso := $state.externalSecrets }}
+{{- $obs := $state.observed }}
+
+{{- if and $eso.enabled $obs.argocd.ready }}
+---
+apiVersion: kubernetes.m.crossplane.io/v1alpha1
+kind: Object
+metadata:
+  name: {{ $state.name }}-argocd-repo-creds
+  annotations:
+    {{ setResourceNameAnnotation "external-secret-argocd-repo-creds" }}
+  labels: {{ $state.labels | toJson }}
+spec:
+  managementPolicies: {{ $state.managementPolicies | toJson }}
+  forProvider:
+    manifest:
+      apiVersion: external-secrets.io/v1
+      kind: ExternalSecret
+      metadata:
+        name: argocd-repo-creds-github
+        namespace: {{ $state.argocd.namespace }}
+      spec:
+        refreshInterval: 1h
+        secretStoreRef:
+          name: {{ $eso.secretStoreName }}
+          kind: ClusterSecretStore
+        target:
+          name: argocd-repo-creds-github
+          creationPolicy: Owner
+          template:
+            metadata:
+              labels:
+                argocd.argoproj.io/secret-type: repo-creds
+            type: Opaque
+            data:
+              type: git
+              url: https://github.com/{{ $state.repository.org }}
+              githubAppID: {{ `"{{ .githubAppID }}"` }}
+              githubAppInstallationID: {{ `"{{ .githubAppInstallationID }}"` }}
+              githubAppPrivateKey: {{ `"{{ .githubAppPrivateKey }}"` }}
+        data:
+        - secretKey: githubAppID
+          remoteRef:
+            key: {{ $eso.githubApp.secretPath }}
+            property: {{ $eso.githubApp.appIdKey }}
+        - secretKey: githubAppInstallationID
+          remoteRef:
+            key: {{ $eso.githubApp.secretPath }}
+            property: {{ $eso.githubApp.installationIdKey }}
+        - secretKey: githubAppPrivateKey
+          remoteRef:
+            key: {{ $eso.githubApp.secretPath }}
+            property: {{ $eso.githubApp.privateKeyKey }}
+  providerConfigRef:
+    name: {{ $state.kubernetesProviderConfigRef.name }}
+    kind: {{ $state.kubernetesProviderConfigRef.kind }}
+
+{{- if $obs.repoCreds.ready }}
+---
+apiVersion: protection.crossplane.io/v1beta1
+kind: Usage
+metadata:
+  name: {{ $state.name }}-delete-repo-creds-before-argocd
+  annotations:
+    {{ setResourceNameAnnotation "usage-repo-creds-argocd" }}
+  labels: {{ $state.labels | toJson }}
+spec:
+  replayDeletion: true
+  of:
+    apiVersion: helm.m.crossplane.io/v1beta1
+    kind: Release
+    resourceRef:
+      name: {{ $state.argocd.name }}
+  by:
+    apiVersion: kubernetes.m.crossplane.io/v1alpha1
+    kind: Object
+    resourceRef:
+      name: {{ $state.name }}-argocd-repo-creds
+{{- end }}
+
+{{- end }}
diff --git a/tests/test-render/main.k b/tests/test-render/main.k
diff --git a/upbound.yaml b/upbound.yaml
