Custom Providers
Atom uses a provider pattern for several extensibility points. Implement these interfaces to integrate with custom backends. Implement one when the built-in providers and modules do not cover your secret store, artifact storage, or reporting target.
ISecretsProvider
Retrieve secrets from a custom store:
public class MySecretsProvider : ISecretsProvider
{
public async ValueTask<string?> GetSecretAsync(string key, CancellationToken cancellationToken)
{
// Return the secret value, or null to delegate to the next provider.
return await MyVault.TryGetAsync(key, cancellationToken);
}
}
Atom prefetches the secrets used by the targets being run asynchronously, passing the build's cancellation token. A
secret that was not prefetched is resolved by blocking on GetSecretAsync with CancellationToken.None, so apply a
timeout to any network call (see Secrets).
Register it:
builder.Services.AddSingleton<ISecretsProvider, MySecretsProvider>();
Multiple providers form a chain — return null to pass through.
IArtifactProvider
Store and retrieve build artifacts in a custom location:
public class MyArtifactProvider : IArtifactProvider
{
// Param names the artifact targets require, and ones they may use (e.g. alternative credentials)
public IReadOnlyList<string> RequiredParams => [nameof(IMyStorage.MyStorageUrl)];
public IReadOnlyList<string> OptionalParams => [nameof(IMyStorage.MyStorageToken)];
public Task StoreArtifacts(IEnumerable<string> artifactNames, string? buildId, string? buildSlice, CancellationToken ct)
{
// Upload artifacts
}
public Task RetrieveArtifacts(IEnumerable<string> artifactNames, string? buildId, string? buildSlice, CancellationToken ct)
{
// Download artifacts
}
public Task Cleanup(IEnumerable<string> runIdentifiers, CancellationToken ct)
{
// Remove old artifacts
}
public Task<IReadOnlyList<string>> GetStoredRunIdentifiers(string? artifactName, string? buildSlice, CancellationToken ct)
{
// List known runs
}
}
Register as a singleton — only one IArtifactProvider is active at a time. RequiredParams are validated before the
artifact targets run; OptionalParams are declared as used parameters so that secrets among them are prefetched and can
be injected into generated workflows, but the provider validates them itself.
IVariableProvider
Read and write workflow variables via a custom mechanism:
public class MyVariableProvider : IVariableProvider
{
public Task<bool> WriteVariable(string variableName, string variableValue, CancellationToken ct)
{
// Return true if handled, false to delegate
}
public Task<bool> ReadVariable(string jobName, string variableName, CancellationToken ct)
{
// Return true if found, false to delegate
}
}
Multiple providers form a chain.
IBuildIdProvider / IBuildVersionProvider / IBuildTimestampProvider
Replace how the build identity is determined:
public class MyVersionProvider : IBuildVersionProvider
{
// Version is a SemVer, not a string.
public SemVer Version => SemVer.Parse(ReadVersionFromSomewhere());
}
public class MyBuildIdProvider : IBuildIdProvider
{
public string BuildId => Guid.NewGuid().ToString();
}
public class MyTimestampProvider : IBuildTimestampProvider
{
// Seconds since the Unix epoch (UTC).
public long Timestamp => DateTimeOffset.UtcNow.ToUnixTimeSeconds();
}
IPathProvider
Add custom well-known paths:
public class MyPathProvider : IPathProvider
{
public RootedPath? GetPath(string key) => key switch
{
"MyCustomPath" => new RootedPath(fileSystem, "/custom/path"),
_ => null,
};
}
IOutcomeReportWriter
Write build reports to a custom destination:
public class MyReportWriter : IOutcomeReportWriter
{
// Write report data to Slack, email, a database, etc.
}
Next steps
- Source Generators: how Atom wires builds together.
- Writing a Module: package providers for reuse.
- ISecretsProvider
- IArtifactProvider
- IVariableProvider
- IOutcomeReportWriter