akuity/kargo v1.10.0

on GitHub

🧬 Kargo v1.10.0 is here! This release is packed with a host of UI and quality-of-life enhancements. The goal for this release was "evolution, not revolution." Highlights are below.

🚨 Breaking Changes

• The optional second arugment for freightMetadata that was deprecated in v1.8.0 has now been removed. If you were using this argument before, use either dot notation (freightMetadata(freightName).keyName) or map access syntax (freightMetadata(freightName)['key-name']) to access specific values

⚠️ New Deprecations

• git-push Default Integration Policy Changing in v1.12.0: The git-push step now supports four configurable push integration policies that control how remote changes are integrated before pushing: AlwaysRebase, RebaseOrMerge, RebaseOrFail, and AlwaysMerge. The current default remains AlwaysRebase (i.e. the current behavior), but the default will change to RebaseOrMerge in v1.12.0. RebaseOrMerge uses signature-trust analysis to prefer rebase when safe but falls back to a merge commit when a rebase would alter commit signature semantics. If you rely on the current unconditional rebase behavior, set the policy explicitly via the [controller.gitClient.pushIntegrationPolicy](https://docs.kargo.io/operator-guide/advanced-installation/common configurations#push-integration-policy) Helm value before upgrading to v1.12.0.

• SSH URLs and SSH Private Keys for Git Repositories: SSH-based Git credentials are deprecated and scheduled for removal in v1.13.0. SSH keys cannot authenticate to git provider APIs, forcing users to maintain two sets of credentials. Use HTTPS URLs with a personal access token or equivalent instead. See #5858 for details.

• createTargetBranch Option in git-open-pr Promotion Step: The createTargetBranch option has been deprecated as the feature never worked. It is scheduled for removal in v1.12. See #5847 for details.

• git-commit Step author Field: The author configuration block (including name, email, and signingKey) on the git-commit step is deprecated and scheduled for removal in v1.12.0. Authorship and signing configuration should be set in the git-clone step or via ClusterConfig instead, as git-clone is the single authority for work tree identity and signing configuration. All downstream steps inherit from it.

🪜 New and Improved Promotion Steps

New Steps

• argocd-wait: Blocks a promotion until one or more Argo CD Applications reach desired health, sync, and operation statuses. Unlike argocd-update (which can already wait), argocd-wait is useful when you need to gate on Argo CD application health without triggering a sync -- for example, waiting for a separate deployment tool to finish before proceeding. (docs)

• oci-push: Copies or retags OCI artifacts (container images and Helm charts) between registries, with support for single images, multi-arch image indexes, and OCI Helm charts. Supports optional annotation injection and shares credential resolution with the existing oci-download step. (docs)

• git-tag: Creates annotated or lightweight Git tags, with optional GPG signing. Pair with git-push (which now supports pushing tags) to tag a verified build only after it passes promotion through a testing Stage. (docs)

• github-push: An alternative to git-push that replays commits through the GitHub REST API, enabling GitHub's native commit verification ("Verified" badge) when authenticating with a GitHub App installation token. Trust is determined by GPG signature status: commits signed by a trusted key are verified by GitHub, while untrusted commits preserve their original attribution. Supports the same push integration policies as git-push. (docs)

• fail: Unconditionally fails the promotion with a configurable message. Combined with conditional step execution (if: expressions), this provides a clean way to fail a promotion pipeline based on evaluated conditions. (docs)

• set-freight-alias: Assigns a custom, human-readable alias to a piece of Freight during a promotion pipeline, improving visibility in the UI -- especially useful in pre-processing Stages where a meaningful name can be set before downstream promotions begin. (docs)

• toml-parse / toml-update: Parse and update TOML files, complementing the existing JSON and YAML equivalents. The update step modifies scalar values in-place while preserving all other bytes. Useful for kcl.mod files or other TOML-based configuration. (toml-parse, toml-update)

Improvements to Existing Steps

• git-merge-pr: Now supports a mergeMethod field, allowing you to choose between merge, squash, and rebase strategies when merging pull requests. (docs)

• git-open-pr: Detects when there are no commits between source and target branches and skips gracefully rather than failing the promotion. git-wait-for-pr is also skipped in that case. This prevents promotions from failing unnecessarily in multi-stage pipelines where some Stages have no effective diff to promote. (docs)

📦 Warehouse Improvements

• since Date Limiter for Git Subscriptions: A new since field limits commit discovery to commits newer than a specified date, directly addressing performance problems in monorepos with large commit histories where unbounded git log operations were a primary source of slowness. (docs)

• Chart Subscription TLS Skip: Chart subscriptions now support insecureSkipTLSVerify, matching the option already available on Git and image subscriptions. Useful for internal registries with self-signed or custom CA certificates. (docs)

• Webhook Path Filtering: GitHub push-event webhooks now evaluate each Warehouse's includePaths/excludePaths against the files changed in a push before marking it for refresh, rather than refreshing all Warehouses and filtering later during reconciliation. This can dramatically reduce unnecessary refresh traffic in monorepo environments with many Warehouses. (docs)

🔄 Shared Resource Replication

Secrets and ConfigMaps in the shared resources namespace can now be automatically replicated to all Project namespaces by annotating them with kargo.akuity.io/replicate-to: "*". This enables workloads in Project namespaces (such as Argo Rollouts AnalysisTemplate Jobs) to consume shared resources that would otherwise require cross-namespace references. Replicated resources are immutable and cleaned up automatically when the source is deleted or the annotation is removed. (docs)

🖥️ UI Improvements

• "My Projects" Filter: The project list now defaults to showing only projects where you've been explicitly mapped via OIDC claims, making it easier to find your projects in large organizations.

• Page Titles: Browser tabs now reflect the current context (project name, Stage name, etc.) so you can distinguish between multiple Kargo tabs at a glance.

• Version-Matched CLI Downloads: The CLI download page now links to the specific version of Kargo currently running rather than always pointing to "latest," preventing inadvertent version mismatches.

• Git Commit Deep Links for Self-Hosted Providers: Commit links now work correctly for self-hosted GitHub Enterprise and GitLab instances, not just github.com and gitlab.com.

• Inline Promotion Step Errors: Errors are now displayed directly beneath the failed step with the step highlighted in red, rather than only in a disconnected banner. Skipped steps are visually muted.

• Smooth Freight List Scrolling: The freight list now scrolls smoothly rather than jumping between positions.

• Improved Status Colors: Non-failed, non-errored statuses now show a neutral color instead of potentially misleading indicators.

⎈ Helm Chart Improvements

• priorityClassName Configuration: Operators can now assign scheduling priority to Kargo components, preventing them from being evicted in favor of higher-priority workloads when resources are constrained.

• Startup Probe for Large Clusters: The API server now has a startup probe with a 5-minute window, preventing the pod from being killed before its initial cache sync completes in large clusters with many resources.

• Certificate Group Enforcement: The group field on cert-manager Certificate resources is now explicitly set, preventing renewal failures that could occur after approximately one year.

🔧 API & Developer Experience

• REST API Client Module: The generated Go client for the Kargo REST API has been extracted into its own Go module with minimal dependencies, making it easier for external consumers to import without pulling in the full Kargo dependency tree.

• Swagger API Documentation: Auto-generated OpenAPI documentation for the Kargo REST API is now embedded in the documentation site.

• Port Numbers in OCI Image Refs: The oci-download step now accepts image references with explicit port numbers (e.g., registry.internal:5000/image:tag).

🐛 Notable Bug Fixes

• yaml-update escaping: Dots in YAML key names can now be properly escaped using backslash notation (e.g., metadata.annotations.example\.com/version). (docs)

• Argo CD App Status Responsiveness (#5995): Eliminated a 10-second cooldown that could cause promotions to stall for minutes in "Unknown" health state. The controller now trusts health immediately when Argo CD's reconciledAt timestamp confirms a fresh reconciliation, and forces a hard refresh otherwise.

• Path Filtering on Merge Commits (#5990, #5999): Fixed two related issues where includePaths/excludePaths filtering on Warehouses could silently skip changes introduced via merge commits. The --first-parent flag is now used to correctly identify files changed by a merge.

• ClusterRole Permissions in Kargo Roles (#5916): Fixed a bug since v1.4.4 where RoleBindings referencing a ClusterRole (instead of a namespaced Role) caused "Role not found" errors, breaking the RBAC UI for any namespace with such bindings.

• Promotion Working Directory Cleanup (#5805): Temporary promotion working directories are now cleaned up when a promotion reaches a terminal state or is deleted, preventing disk space leaks on the controller.

• git-commit Custom Author (#5857): Fixed a regression where using the author config block in the git-commit step failed with "Author identity unknown."

• Promotion Failed vs Errored Status (#5941): Steps that intentionally return Failed status (such as the new fail step) are no longer incorrectly reported as Errored.

• Events Dropped on Shutdown (#5943): Kubernetes events are no longer silently dropped when the controller's context is cancelled during shutdown.

• API Delete Error Handling (#5870): The API server no longer silently swallows errors when deleting resources.

• UI: Invalid Metric Chart Date (#5733): Fixed "Invalid date" display in verification metric chart tooltips.

• UI: Freight Assembly Crash (#5975): Fixed a crash on the freight assembly page when commits were not found for a Git subscription.

🙏 Special Thanks

Thank you to community members who made their first contributions in this release or a recent v1.9
patch release!

Full Changelog: v1.9.5...v1.10.0