HIP for expanding digest support

hips/hip-9999.md

@@ -0,0 +1,117 @@
+---
+hip: 9999
+title: "Expand support for referencing and managing charts by digest"
+authors: [ "Andrew Block <andy.block@gmail.com>" ]
+created: "2026-06-02"
+type: "feature"
+status: "draft"
+---
+
+## Abstract
+
+Helm supports referencing OCI-based charts by digest during install, template, and upgrade operations. This proposal expands this existing functionality for specifying charts using an immutable cryptographic identifier (`sha256:abc123...`) by adding more holistic support across Helm lifecycle operations and dependency management.
+
+## Motivation
+
+### Current Limitations
+
+Helm currently supports referencing OCI-based charts by digest for install, template, and upgrade operations. While this capability provides the baseline level of functionality, there are gaps in its coverage for lifecycle management operators as well as it does not extend to dependency management. Chart dependencies in `Chart.yaml` can only be specified by version, which corresponds to a mutable tag. The `helm dependency` subcommand has no awareness of digests when determining dependant charts. Additionally, once a chart is installed, there is no record of the specific digest that was used, making it difficult to audit or reproduce deployments at the artifact level.
+
+### Real-World Impact
+
+Without native digest support across the full chart lifecycle, users who need to pin to exact artifacts — for reproducibility, compliance, or supply chain security — must rely on tooling and processes outside of Helm to verify that chart versions match their expected digests. This applies to both the top-level chart and all of its dependencies, creating a significant operational burden.
+
+### Who Is Affected
+
+- **Chart authors** who want to pin dependencies to exact artifacts rather than mutable version tags
+- **End users and platform teams** who need to verify and audit exactly which chart artifacts were deployed
+- **Security and compliance teams** who require artifact-level traceability across the software supply chain
+
+## Rationale
+
+### Natural Extension of Existing Capabilities
+
+Helm already supports digest-based references for OCI charts during install, template, and upgrade operations. Extending this support to dependency management, release tracking, and CLI output is the natural evolution of this capability. Rather than introducing an entirely new mechanism, this proposal builds on the existing OCI based artifact infrastructure to provide consistent behavior across the full chart lifecycle.
+
+### Consistency Across the Chart Lifecycle
+
+By supporting digests in `Chart.yaml` dependencies, `Chart.lock`, release metadata, and CLI output (`helm get`, `helm list`), users gain a unified model for artifact-level pinning from authoring through deployment and audit. This eliminates the need for external tooling to fill gaps in Helm's native capabilities.
+
+## Specification
+
+### Expanded --version flag for Lifecycle Operations
+
+Helm already includes a `--version` parameter for `install`, `upgrade`, and `template` operations. Currently, this flag is limited to resolving to an OCI tag. Expand the representation within the `--version` flag to also include additional ways a specific chart chan be referenced.
+
+The following are valid options when specifying the `--version` flag:
+
+* Chart version (Tag only only and represents the existing functionality) - `1.2.3`
+* Digest - `sha256:abc123...`
+* Tag + Digest - `1.2.3@sha256:123`
+
+### Chart.yaml Dependency Considerations
+
+Similar to how references to a specific OCI based chart is expanded for the `--version` flag for lifecycle operations, the same enhanced functionality is also applied to the `version` field within the dependencies section of the `Chart.yaml`
+
+### Chart.lock
+
+The `Chart.lock` file is extended to include a `digest` field for each resolved dependency:
+
+```yaml
+dependencies:
+  - name: mychart
+    version: "1.2.3"
+    repository: "oci://registry.example.com/charts"
+    digest: "sha256:abc123..."
+```
+
+The `helm dependency update` and `helm dependency build` subcommands resolve and record the version and digest of the resolved chart. The `version` field relates to the explicit `version` field as defined in the resolved `Chart.yaml` file. The `digest` field is populated based on the digest of the OCI based chart.
+
+### Release Metadata
+
+Regardless of whether a digest was explicitly specified by the user, the digest of the chart used during installation is recorded in the Helm release metadata (stored in the release secret or specified backend). This enables post-deployment auditing and artifact traceability.
+
+### CLI Output
+
+The recorded digest is surfaced through:
+
+- **`helm get`** — displays the digest of the chart used for the release
+- **`helm list`** — includes the digest in release listing output
+
+## Backwards Compatibility
+
+This proposal is fully backwards compatible. The existing logic for resolving chart versions as defined in the `--version` flag as well as the `version` field of the `Chart.yaml` continue to apply. The changes to the `Chart.lock` are forward looking and do not impact existing charts.
+
+## Security Implications
+
+This proposal strengthens Helm's security posture by enabling artifact-level pinning and traceability across the chart lifecycle. Recording digests in release metadata provides an auditable record of exactly which artifacts were deployed, supporting supply chain security practices.
+
+The proposal otherwise doesn't incur any security implications for Helm. The same version to digest resolution process already occurs today, but this proposal enables the pinning of (cryptographically secure) digests at dependency build time.
+
+## How to Teach This
+
+Documentation should be added to incorporate the enhanced ways of specifying chart versions including where they can be defined (within the CLI and the `Chart.yml` file) including how `version` and `digest` fields are surfaced in the `helm get` and `helm list` commands. 
+
+Guidance should also be provided to enable users to identify the digest of a chart. Chart creators or end users who manage Chart distribution can reference the digest property as it is provided as an output associated with the `helm push `command.
+
+ Tools such as [ORAS](https://oras.land/) can be used to identify the digest of an existing accessible chart.
+
+## Reference Implementation
+
+No reference implementation exists at this time.
+
+## Rejected Ideas
+
+None at this time.
+
+## Open Issues
+
+- [Support digest references for `oci://` dependencies (helm/helm#32133)](https://github.com/helm/helm/issues/32133)
+- [No way to figure out where Helm chart came from (helm/helm#31999)](https://github.com/helm/helm/issues/31999)
+- [Helm supply chain security (helm/helm#10644)](https://github.com/helm/helm/issues/10644)
+- [What do you want to see in OCI Support? (helm/helm#10312)](https://github.com/helm/helm/issues/10312)
+
+## References
+
+- [ORAS](https://oras.land/)
+- [OCI Distribution Specification](https://specs.opencontainers.org/distribution-spec)