Add `WithBuildSecret` overload that accepts a file path
- Dominant language
- C#
- Stars
- 6.3k
- Forks
- 991
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 196
Description
# Add `WithBuildSecret` overload that accepts a file path
## Background and Motivation
Currently, `WithBuildSecret` only supports passing build secrets via `IResourceBuilder`, which requires secrets to be stored in configuration or user secrets. However, there are legitimate scenarios where developers have existing secret files on disk that they need to pass to Docker builds without converting them to Aspire parameters first.
The `WithBuildSecret(FileInfo)` overload was previously removed in version 8.2.0, but there are valid use cases for reading secrets directly from files during container builds, similar to how Docker and Podman natively support `--secret id=name,src=filepath` syntax.
## Use Cases
1. **CI/CD Integration**: Build agents may write secrets to temporary files that need to be consumed by container builds
2. **Local Development**: Developers may have API keys, certificates, or tokens stored in specific files outside the standard configuration system
3. **Legacy Integration**: Existing build processes that already use file-based secrets
4. **Security Tools**: Secret management tools that output secrets to files
## Proposed API
Add a new `WithBuildSecret` overload to `ContainerResourceBuilderExtensions`:
```csharp
///
/// Adds a build secret to the container build process using a file path.
///
/// The type of container resource.
/// The resource builder for the container resource.
/// The name of the secret build argument.
/// The path to the file containing the secret value.
/// The .
///
/// Thrown when is called before .
///
///
///
/// The extension method results in a --secret
/// argument being passed to the underlying container build command with the format
/// --secret id={name},src={filePath}.
///
///
/// The secret file is read at build time and made available to Dockerfile RUN commands
/// using --mount=type=secret,id={name} syntax. The secret is mounted at
/// /run/secrets/{name} within the container during build.
///
///
/// The secret file must exist and be readable at build time. The file path can be
/// absolute or relative to the build context.
///
///
public static IResourceBuilder WithBuildSecret(this IResourceBuilder builder, string name, string filePath)
where T : ContainerResource
```
## Example Usage
```csharp
var builder = DistributedApplication.CreateBuilder(args);
var container = builder.AddDockerfile("myapp", "relative/context/path")
.WithBuildSecret("API_KEY", "./secrets/api-key.txt")
.WithBuildSecret("CERT_FILE", "/etc/ssl/private/build-cert.pem");
```
**Dockerfile usage:**
```dockerfile
# The API key and certificate are available during build
RUN --mount=type=secret,id=API_KEY \
--mount=type=secret,id=CERT_FILE \
./build-script.sh
```
## Implementation Considerations
1. **Path Validation**: The method should validate that the file exists and is readable at build time
2. **Path Resolution**: Support both absolute and relative paths (relative to build context or AppHost project)
3. **Security**: Ensure the file path doesn't expose sensitive information in logs or manifests
4. **Consistency**: Follow the same patterns as existing `WithBuildSecret` and `WithBuildArg` methods
5. **Documentation**: Clear guidance on when to use file paths vs parameters
## Alternative Solutions Considered
1. **Convert files to parameters**: Developers can manually read files and create parameters, but this adds boilerplate
2. **Use environment variables**: Not suitable for multi-line secrets like certificates
3. **Mount volumes**: More complex and doesn't integrate with Docker build secrets
4. **Mutate DockerfileAnnotation**: Brittle and requires mucking with the raw BuildSecrets dictionary
## Related Issues
- The underlying Docker/Podman build secret functionality supports file paths natively
- This would complement the existing parameter-based `WithBuildSecret` method
- Aligns with Docker's `--secret id=name,src=filepath` syntax
Contributor guide
Assessment
This issue has not been assessed yet.