git-hubby Helm Chart

A Helm chart for the git-hubby Kubernetes operator, managing GitHub resources (organizations, repositories, teams, and security configurations) declaratively via Custom Resource Definitions (CRDs).

Overview

This chart deploys the git-hubby controller manager, a Kubernetes operator that reconciles GitHub resources based on custom resources in your cluster. It manages:

• Organizations — GitHub org settings, Actions permissions, custom properties, code security configurations, and rulesets
• Repositories — Repository settings, merge strategies, deploy keys, webhooks, autolinks, rulesets, custom properties, and code security
• Teams — Team membership via IDP group sync or manual member lists, organization roles
• CodeSecurityConfigurations — GitHub Advanced Security features (code scanning, secret scanning, Dependabot, etc.)
• RulesetPresets — Reusable branch/tag protection rulesets
• WebhookPresets — Reusable webhook configurations
• WebhookIgnorePresets — URL patterns for webhooks to exclude
• AutolinksPresets — Reusable autolink reference configurations

Prerequisites

• Kubernetes 1.19+
• Helm 3+
• cert-manager installed in the cluster (for webhook and metrics TLS certificates)
• A GitHub App installation with appropriate permissions

Installation

helm install git-hubby oci://ghcr.io/interhyp/git-hubby-helm/git-hubby \
  --version <version> \
  -n <namespace> --create-namespace \
  -f my-values.yaml

Custom Resource Definitions (CRDs)

CRDs are located in chart/crds/ and are installed automatically. The API group is github.interhyp.de with version v1alpha1.

CRD	Description
Organization	Manages a GitHub organization's settings, Actions config, custom properties, code security, and rulesets
Repository	Manages a GitHub repository's settings, visibility, merge strategies, webhooks, deploy keys, rulesets, and custom properties
Team	Manages a GitHub team's membership (IDP sync or manual), organization roles
CodeSecurityConfiguration	Defines GitHub Advanced Security feature settings (code scanning, secret scanning, Dependabot, etc.)
RulesetPreset	Defines reusable repository/branch rulesets (protection rules, required checks, etc.)
WebhookPreset	Defines reusable webhook configurations
WebhookIgnorePreset	Defines URL regex patterns to exclude from webhook creation
AutolinksPreset	Defines reusable autolink reference configurations

Configuration Parameters

Controller Manager

Parameter	Description	Default
controllerManager.replicas	Number of controller manager replicas	1
controllerManager.podLabels	Additional labels for controller manager pods	{}
controllerManager.nodeSelector	Node selector for pod scheduling	{}
controllerManager.tolerations	Tolerations for pod scheduling	[]
controllerManager.topologySpreadConstraints	Topology spread constraints for pod distribution (labelSelector auto-injected)	soft spread across nodes
controllerManager.podSecurityContext.runAsNonRoot	Run pods as non-root user	true
controllerManager.podSecurityContext.seccompProfile.type	Seccomp profile type	RuntimeDefault

Manager Container

Parameter	Description	Default
controllerManager.manager.image.repository	Controller container image repository	ghcr.io/interhyp/git-hubby
controllerManager.manager.image.tag	Controller container image tag (defaults to chart appVersion if empty)	""
controllerManager.manager.args	Command-line arguments for the manager	See values.yaml
controllerManager.manager.resources.limits.cpu	CPU resource limit	500m
controllerManager.manager.resources.limits.memory	Memory resource limit	128Mi
controllerManager.manager.resources.requests.cpu	CPU resource request	10m
controllerManager.manager.resources.requests.memory	Memory resource request	64Mi
controllerManager.manager.containerSecurityContext.allowPrivilegeEscalation	Disallow privilege escalation	false
controllerManager.manager.containerSecurityContext.capabilities.drop	Linux capabilities to drop	["ALL"]
controllerManager.manager.containerSecurityContext.readOnlyRootFilesystem	Mount root filesystem as read-only	true

Environment Variables

Parameter	Description	Default
envs	Key-value map of environment variables injected into the manager container via a ConfigMap	{}

Variable	Description	Possible Values	Default
ENABLE_WEBHOOKS	Enables or disables Kubernetes admission webhooks for validating Organization and Repository resources on create/update.	"true", "false"	"true" (enabled unless explicitly set to "false")
GITHUB_MEMBER_SUFFIX	A suffix appended to each team member username before matching/adding them on GitHub. Takes precedence over spec.memberSuffix on the Organization CR. Prefer using spec.memberSuffix for per-organization suffixes in multi-org setups.	Any string (e.g. "_company-name", "")	"" (no suffix)
REPOSITORY_FINALIZER_MODE	Controls what happens to a GitHub repository when its Repository CR is deleted from Kubernetes.	"ignore" (no action), "archive" (archive the repo), "delete" (delete the repo)	"ignore"
ENABLE_STARTUP_SPREADING	Enables startup spreading, which distributes reconciliation requests over time after a controller restart to avoid GitHub API rate limit spikes.	"true", "false"	"true"
SPREAD_INTERVAL_MINUTES	Length (in minutes) of the interval over which delayed reconciliations are randomly distributed. Delayed reconciliations are scheduled between (startup + SpreadPeriod) and (startup + SpreadPeriod + SpreadInterval). This value also serves as the requeue interval after a successful reconciliation.	Any positive integer	180
STARTUP_SPREAD_PERIOD_MINUTES	Duration (in minutes) after pod startup during which unchanged, healthy resources are delayed instead of reconciled immediately. Reconciliations for changed or unhealthy resources are never delayed.	Any positive integer	5
LOG_LEVEL	Sets the minimum log level. Overrides the --zap-log-level CLI flag. Note: warn is not supported due to limitations of the logr API used by controller-runtime — logr only provides Info (with verbosity levels) and Error; there is no distinct warn level. Use info to see all informational and warning-prefixed messages, or error to suppress them.	"debug", "info", "error"	"info"

Service Account

Parameter	Description	Default
serviceAccount.create	Create a ServiceAccount	true
serviceAccount.name	ServiceAccount name (defaults to fullname)	""
serviceAccount.annotations	Annotations for the ServiceAccount	{}
serviceAccount.secrets	Secrets to attach to the ServiceAccount	[]
serviceAccount.automount	Automount the ServiceAccount token	true

Metrics Service

Parameter	Description	Default
metricsService.type	Service type for the metrics endpoint	ClusterIP
metricsService.ports[0].name	Port name	https
metricsService.ports[0].port	Service port	8443
metricsService.ports[0].targetPort	Container target port	8443
metricsService.ports[0].protocol	Protocol	TCP

Webhooks

Parameter	Description	Default
webhooks.enabled	Enable or disable all Kubernetes admission webhook resources (ValidatingWebhookConfiguration, webhook Service, TLS Certificate, Issuer, and NetworkPolicy). Also sets the ENABLE_WEBHOOKS env var on the controller.	true
webhookService.type	Service type for the webhook endpoint	ClusterIP

TLS Certificates (cert-manager)

The chart manages two cert-manager Certificate resources:

• Serving certificate — TLS for the webhook endpoint (Secret webhook-server-certificate). Only rendered when webhooks.enabled=true.
• Metrics certificate — TLS for the metrics endpoint (Secret metrics-server-cert). Always rendered.

Self-signed Issuer

Parameter	Description	Default
selfSignedIssuer.enabled	Create a self-signed cert-manager Issuer (named <fullname>-selfsigned-issuer) and use it as the default issuer for both certificates. Set to false when bringing your own issuer.	true

When selfSignedIssuer.enabled=true and no explicit issuerRef is configured on a certificate, the chart automatically points that certificate at the built-in self-signed issuer. When selfSignedIssuer.enabled=false, an issuerRef must be provided for each certificate that is rendered, otherwise the chart will fail with a descriptive error.

Metrics Certificate (metricsCert)

Parameter	Description	Default
metricsCert.issuerRef	cert-manager issuer reference. Overrides selfSignedIssuer for this certificate.	self-signed issuer
metricsCert.issuerRef.kind	Issuer kind (Issuer or ClusterIssuer)	—
metricsCert.issuerRef.name	Issuer name	—
metricsCert.issuerRef.group	Issuer API group (optional)	—
metricsCert.duration	Certificate validity duration (e.g. 2160h0m0s)	cert-manager default
metricsCert.renewBefore	How long before expiry cert-manager renews the certificate (e.g. 360h0m0s)	cert-manager default
metricsCert.privateKey.algorithm	Private key algorithm (RSA, ECDSA, Ed25519)	cert-manager default
metricsCert.privateKey.size	Private key size in bits	cert-manager default
metricsCert.privateKey.encoding	Private key encoding (PKCS1, PKCS8)	cert-manager default
metricsCert.privateKey.rotationPolicy	Key rotation policy (Never, Always)	cert-manager default
metricsCert.subject	X.509 subject fields (e.g. organizations, countries)	—

Serving Certificate (servingCert)

Parameter	Description	Default
servingCert.issuerRef	cert-manager issuer reference. Overrides selfSignedIssuer for this certificate.	self-signed issuer
servingCert.issuerRef.kind	Issuer kind (Issuer or ClusterIssuer)	—
servingCert.issuerRef.name	Issuer name	—
servingCert.issuerRef.group	Issuer API group (optional)	—
servingCert.duration	Certificate validity duration (e.g. 2160h0m0s)	cert-manager default
servingCert.renewBefore	How long before expiry cert-manager renews the certificate (e.g. 360h0m0s)	cert-manager default
servingCert.privateKey.algorithm	Private key algorithm (RSA, ECDSA, Ed25519)	cert-manager default
servingCert.privateKey.size	Private key size in bits	cert-manager default
servingCert.privateKey.encoding	Private key encoding (PKCS1, PKCS8)	cert-manager default
servingCert.privateKey.rotationPolicy	Key rotation policy (Never, Always)	cert-manager default
servingCert.subject	X.509 subject fields (e.g. organizations, countries)	—
servingCert.usages	Key usages (e.g. server auth, client auth)	—

Example: Bring your own ClusterIssuer

selfSignedIssuer:
  enabled: false

metricsCert:
  issuerRef:
    kind: ClusterIssuer
    name: letsencrypt-prod
  duration: 8760h0m0s
  renewBefore: 720h0m0s

servingCert:
  issuerRef:
    kind: ClusterIssuer
    name: letsencrypt-prod

Other

Parameter	Description	Default
kubernetesClusterDomain	Kubernetes cluster domain suffix	cluster.local
nameOverride	Override the chart name	""
fullnameOverride	Override the full release name	""

Testing

This chart uses helm-unittest for unit testing. Tests are located in the tests/ directory.

Running tests locally

# Install the helm-unittest plugin (one-time)
helm plugin install https://github.com/helm-unittest/helm-unittest.git

# Run all tests
helm unittest .

Tests are also executed automatically in CI on every push to main and on pull requests.

Architecture

The chart deploys:

1. Deployment — The controller manager pod running /manager with webhook and health probe endpoints
2. Services — A metrics service (port 8443) and a webhook service (port 443 → 9443)
3. RBAC — ClusterRoles and bindings for the manager, leader election, metrics auth, and per-CRD admin/editor/viewer roles
4. Certificates — An optional self-signed Issuer (controlled by selfSignedIssuer.enabled), a serving certificate for the webhook endpoint (when webhooks.enabled=true), and a metrics certificate — all via cert-manager. Both certificates fall back to the built-in self-signed issuer unless a custom issuerRef is configured.
5. ValidatingWebhookConfiguration — Admission webhooks validating Organization and Repository resources on CREATE/UPDATE
6. NetworkPolicy — Allows webhook traffic from kube-system namespace to the controller on port 9443
7. ServiceMonitor — Prometheus ServiceMonitor for scraping /metrics from the controller
8. CRDs — All custom resource definitions in crds/

RBAC Roles

The chart creates the following ClusterRoles for each CRD (organization, repository, team, codesecurityconfiguration, rulesetpreset, webhookpreset, webhookignorepreset, autolinkspreset):

Role	Permissions
*-admin-role	Full access (*) to the resource and get on status
*-editor-role	create, delete, get, list, patch, update, watch and get on status
*-viewer-role	get, list, watch and get on status

Additionally:

• *-manager-role — Full operator permissions for all CRDs and secrets
• *-leader-election-role — ConfigMaps, Leases, and Events for leader election
• *-metrics-auth-role — TokenReviews and SubjectAccessReviews for metrics authentication
• *-metrics-reader — Read access to /metrics non-resource URL