HIP for expanding digest support

hips/hip-9999.md

@@ -0,0 +1,132 @@
+---
+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, and the `helm dependency` subcommand has no awareness of digests. 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
+
+### --digest Parameter for Lifecycle Operations
+
+Helm already includes a `--version` parameter for `install`, `upgrade`, and `template` operations. Include support for a `--digest` option to explicitly specify the OCI artifact to reference.
+
+When `--digest` is specified, it takes precedence over `--version` for resolution. If both are provided, Helm validates that the resolved version matches the specified digest and returns an error on mismatch.
+
+### Chart.yaml Dependency Entry
+
+A new optional `digest` field is added to the dependency specification in `Chart.yaml`:
+
+```yaml
+dependencies:
+  - name: mychart
+    version: "1.2.3"
+    repository: "oci://registry.example.com/charts"
+    digest: "sha256:abc123..."
+```
+
+When `digest` is specified, it takes precedence over `version` for resolution. If both are provided, Helm validates that the resolved version matches the specified digest and returns an error on mismatch. See [Behavior Summary](#behavior-summary) for additional details.
+
+### 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 digest for each OCI-based dependency. When a digest is specified in the `Chart.yaml` file, it is used for resolution. When only a version is specified, the digest is resolved from the registry and recorded in the `Chart.lock` file. See [Behavior Summary](#behavior-summary) for additional details.
+
+### 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
+
+### Behavior Summary
+
+The following summary describes the interaction of `version` and `digest` properties as defined explicitly in configuration parameters or inferred through OCI descriptor references.
+
+| Scenario | Behavior |
+|----------|----------|
+| `digest` only | Resolve chart by digest |
+| `version` only | Resolve chart by version, record resolved digest |
+| Both `digest` and `version` | Resolve by digest, validate version matches digest |
+| Neither | Existing behavior (resolve latest matching version) |
+
+## Backwards Compatibility
+
+This proposal is fully backwards compatible. The `digest` field is optional in both `Chart.yaml` and `Chart.lock`. Existing charts without a `digest` field continue to work as they do today. The additional digest tracking in release metadata is transparent to existing workflows.
+
+## 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.
+
+## How to Teach This
+
+Documentation should cover the new `digest` field in `Chart.yaml` and `Chart.lock`, as well as how to view the recorded digest via `helm get` and `helm list`. 
+
+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)