Releases

Flux v2.9.1 is a patch release fixing a CRD schema corruption bug where post-build variable substitution could rewrite Flux's own CRD definitions, plus smaller fixes for SOPS .ini decryption and a dry-run strategic merge patch error. No new breaking changes or CVEs are disclosed.

• breakingCRD schema corruption from variable substitution fixed

  If you run Kustomizations with post-build variable substitution enabled and your manifests contain ${...} sequences that happen to match Flux CRD schema fields, earlier versions could corrupt the CRD schemas. v2.9.1 fixes this by annotating Flux's own CRDs with kustomize.toolkit.fluxcd.io/substitute: disabled, so substitution no longer touches them. Upgrade if you use post-build substitution.

Flux v2.9.0 is a feature release adding capabilities across most controllers, with one breaking change: the end-of-life image.toolkit.fluxcd.io/v1beta2 and notification.toolkit.fluxcd.io/v1beta2 APIs have been removed from the CRDs.

• breakingv1beta2 image and notification APIs removed

  Applies to any cluster still running resources on image.toolkit.fluxcd.io/v1beta2 or notification.toolkit.fluxcd.io/v1beta2. Both APIs have reached end-of-life and were dropped from the CRDs in v2.9.0. Migrate ImagePolicy, ImageRepository, ImageUpdateAutomation, Alert, Provider, and Receiver resources to their current API version before upgrading, or the controllers will fail to reconcile them.

Flux v2.8.8 patches two go-git CVEs in source and image-automation controllers, fixes a memory leak in helm-controller, and adds GCP sovereign cloud registry support.

• securityUpgrade immediately to patch two go-git CVEs

  CVE-2026-45571 and CVE-2026-45570 affect source-controller and image-automation-controller. Both are fixed in go-git v5.19.1 bundled with this release. If you run either of these controllers — and most Flux installations do — upgrade to v2.8.8 now. There's no workaround short of disabling those controllers.

• breakingReview charts that place non-CRD resources under crds/ directory

  Helm-controller previously force-applied any object found under a chart's crds/ directory, not just actual CRDs. That behavior is now corrected. If you have Helm charts (especially community or third-party ones) that bundle non-CRD manifests under crds/ as a workaround for install ordering, those objects will no longer be force-applied. Audit your HelmRelease resources and test in a non-production environment before rolling this out broadly.

• enhancementInvestigate artifact fetch timeouts if reconciliations have been stalling

  The new configurable HTTP timeout for artifact fetching directly addresses indefinite blocking during fetches. If you've seen helm-controller or source-controller reconciliations hang without clear errors, this fix likely explains it. After upgrading, configure the timeout explicitly rather than relying on defaults — check the helm-controller v1.5.5 changelog for the specific field name. Also worth auditing memory usage before and after upgrade if your helm-controller pods have been growing steadily in memory.

Flux v2.8.7 patches a CVE in go-git and fixes a destructive reconciliation bug where non-namespaced resources with ssa:IfNotPresent were being deleted and recreated every cycle.

• securityPatch CVE-2026-45022 by upgrading now

  go-git v5.19.0 fixes CVE-2026-45022, which affects source-controller and image-automation-controller — two components that actively clone and interact with Git repos. If your Flux installation pulls from any external or semi-trusted Git source, treat this as a priority upgrade. Run 'flux install' or update your Helm release to v2.8.7 immediately.

• breakingCheck non-namespaced resources using ssa:IfNotPresent for unintended churn

  If you're managing ClusterRoles, CRDs, or other cluster-scoped resources with the kustomize.toolkit.fluxcd.io/ssa: IfNotPresent annotation, those resources were being silently deleted and recreated on every reconciliation loop before this fix. Audit your Kustomization objects and verify resource state after upgrading to confirm the churn has stopped. Any dependent workloads may have experienced disruptions you weren't aware of.

• enhancementFollow the v2.7+ upgrade procedure if coming from v2.6

  The Flux team has a specific upgrade discussion thread for v2.7+ migrations. Skipping it when jumping from v2.6 to v2.8.7 can cause issues. Review the linked procedure before applying this update in environments running older Flux versions.

Flux v2.8.6 is a patch release fixing helm-controller post-renderer conflicts, a notification-controller regression for generic providers, and adding a MigrateAPIVersion feature gate in kustomize-controller.

• breakingAdd 'audience' to GCR Receiver secrets before upgrading to v2.9

  The 'audience' field on GCR Receiver secrets is currently optional but will become mandatory in v2.9. Audit your Receiver resources now and add the audience field to any GCR-backed secrets. Doing this proactively prevents a hard failure on your next major upgrade.

• breakingGeneric provider commit status events were broken — upgrade immediately if you rely on them

  A regression in notification-controller stopped generic providers from forwarding commit status events. If your CI/CD pipelines depend on those webhooks for pipeline gating or observability, they have been silently failing since the prior release. This patch restores that behavior — upgrade to v2.8.6 without delay.

• enhancementUse MigrateAPIVersion feature gate when managing resources with deprecated API versions

  If kustomize-controller manages resources that use older API versions tracked in managed field entries, the new MigrateAPIVersion feature gate handles migration automatically. Enable it in environments where you're seeing API version drift or drift detection noise from deprecated APIs.

Flux v2.8.5 patches a cache race condition that could freeze Kustomizations, fixes Azure Blob prefix handling, and adds GCR Receiver verification fields.

• breakingStuck Kustomizations? This patch likely fixes you

  If you've seen Kustomizations get stuck after a reconciliation timeout or cancellation — often requiring a manual flux reconcile or pod restart to unblock — the race condition fix in kustomize-controller v1.8.3 directly addresses this. Upgrade to v2.8.5 and monitor your reconciliation loops post-upgrade. No config changes needed, but watch for Kustomizations that were previously stuck to automatically recover.

• breakingVerify Azure Blob prefix filtering actually works after upgrade

  If you're using Bucket sources backed by Azure Blob Storage with a prefix configured, that prefix was not being applied — meaning your source-controller was fetching more objects than intended. After upgrading to v2.8.5, the prefix filter will now take effect. Validate that your expected subset of blobs is still being synced correctly and that no previously-ignored paths break your deployments.

• enhancementTighten GCR webhook security with email and audience verification

  The GCR Receiver now accepts optional 'email' and 'audience' fields. If you're using GCR image push webhooks to trigger Flux reconciliation, add these fields to your Receiver spec to validate the service account identity and token audience — reducing the risk of forged webhook requests. This is opt-in, so existing setups won't break, but teams with strict security postures should configure it.

Flux v2.8.4 is a CLI-only patch fixing two bugs: Windows compatibility for 'flux build/diff ks' and source flag validation in 'create kustomization'.

• breakingCheck your 'create kustomization' scripts for invalid --source values

  The '--source' flag now validates input properly. Scripts or pipelines passing malformed source references that previously slipped through will now fail explicitly. Test your automation before rolling out the updated CLI in CI/CD pipelines.

• enhancementWindows users: upgrade to unblock 'flux build/diff ks'

  If your team uses Windows workstations or CI runners for Flux kustomization diffs, these commands were silently broken. Upgrade the CLI to v2.8.4 — the fix is CLI-side only, so no cluster-side changes are needed.

Flux v2.8.3 fixes a critical helm-controller regression that broke templating for charts containing YAML separators or embedded content.

• breakingUpgrade immediately if using Helm charts with YAML separators

  The regression in v2.8.2 breaks templating for common chart patterns like multi-document YAML files and embedded scripts. Review your Helm deployments for failures and upgrade to v2.8.3 now. Follow the official upgrade procedure for Flux v2.7+ to avoid migration issues.

• enhancementValidate Helm chart deployments after upgrade

  After upgrading, check that previously failing Helm releases now deploy successfully. Pay special attention to charts that embed certificates, scripts, or use multiple YAML documents. This fix restores functionality that may have silently failed in recent versions.

Flux v2.8.2 delivers critical fixes for reconciliation loops, Azure Container Registry authentication, and includes a security patch for CVE-2026-27138. The release focuses on operational stability improvements.

• securityApply CVE-2026-27138 patch immediately

  This release fixes a potential Denial of Service vulnerability during TLS handshakes. Schedule your upgrade to v2.8.2 as soon as possible, especially if your Flux installation handles external TLS connections or operates in environments with security compliance requirements.

• enhancementEnable DefaultToRetryOnFailure for better HelmRelease reliability

  If you use CancelHealthCheckOnNewRevision and have experienced stuck HelmReleases, enable the new DefaultToRetryOnFailure feature gate. This prevents canceled releases without retry strategies from hanging indefinitely, improving deployment reliability.

• enhancementVerify Azure Container Registry authentication after upgrade

  The ACR authentication scope fix may resolve intermittent authentication failures you've experienced with Azure registries. After upgrading, monitor your image pulls and source operations to confirm improved reliability with ACR repositories.

Flux v2.8.1 is a patch release fixing critical issues with Git commit status notifications and StatefulSet health checks during Pod scheduling problems.

• enhancementUpgrade to fix Git integration issues

  If you're experiencing missing Git commit status updates or notifications, upgrade to v2.8.1. The fix ensures proper Git webhook integration and status reporting for your GitOps workflows. Follow the official upgrade procedure for Flux v2.7+ to avoid disruption.

• enhancementResolve StatefulSet monitoring problems

  Upgrade if you have StatefulSets that show incorrect health status when Pods are stuck in Pending state due to resource constraints or scheduling issues. This fix provides more accurate deployment status reporting, improving your observability during rollouts.

Flux v2.8.0 introduces major GitOps capabilities including Helm v4 support, enhanced observability, faster recovery times, and improved notification features while removing deprecated APIs.

• breakingMigrate from deprecated v1beta2/v2beta2 APIs immediately

  Deprecated APIs have been removed from CRDs. Follow the official upgrade procedure for Flux v2.7+ to migrate your resources to supported API versions before upgrading to v2.8.0.

• enhancementEnable faster application recovery with new feature gate

  Activate the CancelHealthCheckOnNewRevision feature gate on your Kustomizations and HelmReleases to reduce recovery time during application failures by canceling health checks when new revisions are detected.

• enhancementImplement automated PR notifications for GitOps workflows

  Configure Pull Request commenting in your notification providers to enable direct feedback from Flux deployments to development teams, improving visibility and collaboration in GitOps workflows.