Install

The operator ships as a Helm chart that installs the CRDs, the operator Deployment and its admission webhook. Forgejo itself is not part of it.

Before you beginCopy Anchor Link

• Kubernetes 1.30+ (the chart refuses older clusters), with kubectl and helm 3.8+ (for OCI charts).
• cert-manager, which issues the admission webhook's TLS certificate. You can do without it and bring your own certificate.
• Forgejo v16 or later. Older versions lack the admin token API the operator relies on, and their ForgejoInstance reports UnsupportedForgejoVersion.

InstallCopy Anchor Link

helm install weebo-forgejo oci://ghcr.io/batleforc/charts/weebo-forgejo \
  --namespace weebo-forgejo --create-namespace --version X.Y.Z

Versions are listed on the releases page. Every image and chart is signed; see Verify a release to check them before installing.

Check the installCopy Anchor Link

kubectl -n weebo-forgejo get pods
kubectl get crd | grep forgejo.weebo.io

Two Running pods and eleven CRDs mean you're ready to connect a Forgejo.

Use your own certificate issuerCopy Anchor Link

By default the chart creates a self-signed cert-manager Issuer for the webhook. To use an existing issuer instead:

helm install weebo-forgejo oci://ghcr.io/batleforc/charts/weebo-forgejo \
  --namespace weebo-forgejo --create-namespace \
  --set certManager.createIssuer=false \
  --set certManager.issuerRef.name=my-issuer \
  --set certManager.issuerRef.kind=ClusterIssuer

Without cert-managerCopy Anchor Link

Set webhook.certManager.enabled=false and provide the certificate yourself:

1. A kubernetes.io/tls Secret in the release namespace, valid for <release>-weebo-forgejo.<namespace>.svc (or weebo-forgejo.<namespace>.svc when the release is called weebo-forgejo).
2. The CA that signed it, base64-encoded, as webhook.caBundle. The API server uses it to trust the webhook.

# Example with a throwaway CA; use your PKI in production.
SVC=weebo-forgejo.weebo-forgejo.svc
openssl req -x509 -newkey rsa:2048 -nodes -days 365 -subj "/CN=weebo-ca" \
  -keyout ca.key -out ca.crt
openssl req -newkey rsa:2048 -nodes -subj "/CN=$SVC" -keyout tls.key -out tls.csr
openssl x509 -req -in tls.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 365 \
  -extfile <(printf "subjectAltName=DNS:%s,DNS:%s.cluster.local" "$SVC" "$SVC") -out tls.crt
kubectl -n weebo-forgejo create secret tls weebo-forgejo-webhook-tls --cert tls.crt --key tls.key

helm install weebo-forgejo oci://ghcr.io/batleforc/charts/weebo-forgejo \
  --namespace weebo-forgejo \
  --set webhook.certManager.enabled=false \
  --set webhook.tls.secretName=weebo-forgejo-webhook-tls \
  --set webhook.caBundle="$(base64 -w0 < ca.crt)"

The operator reloads the certificate every 60 s: renew the Secret in place before it expires, with the same CA (or update webhook.caBundle first).

What gets deployedCopy Anchor Link

Main valuesCopy Anchor Link

Every value is validated against the chart's values.schema.json: a typo or an invalid enum fails the install instead of being ignored. helm show values oci://ghcr.io/batleforc/charts/weebo-forgejo prints them all with their comments.

Release artifactsCopy Anchor Link

Both images also contain weebo-forgejo-importer, used to migrate an existing Forgejo. They carry an SBOM and SLSA provenance, and are signed with cosign.

CRDsCopy Anchor Link

The chart renders the CRDs as regular templates (templates/crds/), not from Helm's crds/ directory, which Helm installs once and never upgrades. So helm upgrade upgrades the CRDs too. Each CRD carries helm.sh/resource-policy: keep: helm uninstall, or switching crds.install off, never deletes them, and with them every CR.

If you manage CRDs separately (GitOps with a dedicated CRD stage, or a cluster where only admins may write CRDs), install with crds.install=false and apply the release's bundle yourself, before each chart upgrade:

kubectl apply --server-side \
  -f https://github.com/batleforc/weebo-forgejo/releases/download/vX.Y.Z/weebo-forgejo-crds.yaml

UpgradeCopy Anchor Link

helm upgrade weebo-forgejo oci://ghcr.io/batleforc/charts/weebo-forgejo \
  --namespace weebo-forgejo --version X.Y.Z

The CRDs are upgraded with the chart. Read the release notes first: they list any CRD or value change.

Upgrading to a release on weebo-operator-kit v0.14Copy Anchor Link

The token Secret of every ForgejoLocalInstance must carry the label forgejo.weebo.io/instance-token: "true"; without it the instance is Ready: False (TokenSecretNotAllowed) and its CRs stop reconciling. Label them before upgrading:

kubectl get forgejolocalinstances -A \
  -o jsonpath='{range .items[*]}{.metadata.namespace} {.spec.tokenSecretRef.name}{"\n"}{end}' |
  while read -r ns secret; do
    kubectl -n "$ns" label secret "$secret" forgejo.weebo.io/instance-token=true --overwrite
  done

ForgejoInstance (cluster-scoped, created by cluster admins) needs no label.

Likewise, the Secrets a CR hands to Forgejo — migrate.authSecretRef of a ForgejoRepository, secretRef and authorizationHeaderSecretRef of a ForgejoWebhook — must carry forgejo.weebo.io/credential: "true" (SecretNotAllowed otherwise; webhooks re-read theirs on every reconcile):

kubectl get forgejowebhooks -A -o json | jq -r '.items[] | .metadata.namespace as $ns |
  (.spec.secretRef.name, .spec.authorizationHeaderSecretRef.name) // empty | "\($ns) \(.)"' |
  sort -u | while read -r ns secret; do
    kubectl -n "$ns" label secret "$secret" forgejo.weebo.io/credential=true --overwrite
  done

Upgrading from chart 0.1.0Copy Anchor Link

Chart 0.1.0 installed the CRDs from crds/, outside the Helm release. The first upgrade to a chart that templates them fails with invalid ownership metadata unless the existing CRDs are handed over to the release first (nothing is deleted or recreated):

RELEASE=weebo-forgejo NAMESPACE=weebo-forgejo
for crd in $(kubectl get crd -o name | grep '\.forgejo\.weebo\.io$'); do
  kubectl label "$crd" app.kubernetes.io/managed-by=Helm --overwrite
  kubectl annotate "$crd" meta.helm.sh/release-name="$RELEASE" \
    meta.helm.sh/release-namespace="$NAMESPACE" --overwrite
done

The leader-election Lease keeps its name, weebo-forgejo-operator-leader: old and new replicas compete for the same Lease during the rolling update, so there is never more than one leader. Only a second release in the same namespace needs its own (--set leaderElection.leaseName=…).

UninstallCopy Anchor Link

helm uninstall weebo-forgejo --namespace weebo-forgejo

This removes the operator but keeps the CRDs and your CRs, so nothing in Forgejo is touched. Deleting the CRDs deletes every CR. Only do that after the operator has cleaned up whatever it should (see Deletion): delete your CRs first, then the ForgejoInstances — an instance's finalizer holds it while CRs are still bound to it, since their own cleanup needs it.

A CR whose cleanup can't succeed any more (its instance or token already gone) stays in Terminating with a Warning Event of action Cleanup. Release it without touching Forgejo or its Secrets:

kubectl annotate forgejorepository app forgejo.weebo.io/force-orphan=true

NextCopy Anchor Link

Connect a Forgejo.