Atom

Atom is an opinionated, type-safe build automation framework for .NET. It enables you to define your build logic in C#, debug it like standard code, and automatically generate CI/CD configuration files for GitHub Actions and Azure DevOps.

Why Atom?

• Zero Context Switching: Write build logic in C# alongside your application code.
• Intellisense & Debugging: Step through your build process using your IDE.
• CI/CD Agnostic: Define logic once; Atom generates the YAML for GitHub and Azure DevOps.
• Modular: Pull in capabilities via NuGet packages (GitVersion, Azure KeyVault, etc.).
• Source Generators: Reduces boilerplate by automatically discovering targets and parameters.

Basic Example

1. Create a new file Build.cs

   #:package DecSm.Atom@2.*
   
   [BuildDefinition]
   [GenerateEntryPoint]
   partial class Build : BuildDefinition
   {
       Target SayHello => t => t
           .Executes(() => Logger.LogInformation("Hello, World!"));
   }
   

2. Execute dotnet run Build.cs SayHello

   25-12-16 +10:00  DecSm.Atom.Build.BuildExecutor:
   22:46:01.754 INF Executing build
   
   SayHello
   
   25-12-16 +10:00  SayHello | Build:
   22:46:01.790 INF Hello, World!    
   
   Build Summary
   
     SayHello │ Succeeded │ <0.01s
   

Documentation

Getting Started

• Introduction — What Atom is and why you'd use it
• Your First Build — Create a minimal build and run it
• Base vs Workflow Build — BuildDefinition vs WorkflowBuildDefinition

Core Concepts

• Build Definitions — The [BuildDefinition] attribute and source generators
• Targets — Defining targets with the fluent TargetDefinition API
• Parameters — Declaring, requiring, and resolving parameters
• Secrets — Secure parameter handling with ISecretsProvider
• Artifacts — Producing and consuming build artifacts
• Variables — Sharing data between targets with workflow variables
• File System — IAtomFileSystem, RootedPath, and path providers
• Process Runner — Executing external processes
• Build Info — Build ID, version, and timestamp providers
• Build Options — Configuring build behaviour with IBuildOption
• Hosting — AtomHost, [GenerateEntryPoint], and host configuration
• Lifecycle Hooks — IAtomLifecycleHook for pre/post-build logic
• Logging & Reports — Spectre console output and report data
• File Transformations — Temporary, reversible file edits with TransformFileScope

Workflows

• Overview — What workflows add on top of a base build
• Workflow Definitions — WorkflowDefinition, targets, and types
• Triggers — Push, pull request, and manual triggers
• Workflow Options — Checkout, deployment, conditions, and more
• Variables in Workflows — Cross-job data sharing
• Debugging Workflows — Local workflow simulation

Modules

• Overview — What a module is and how to add one
• .NET — DecSm.Atom.Module.Dotnet
• GitHub Workflows — DecSm.Atom.Module.GithubWorkflows
• DevOps Workflows — DecSm.Atom.Module.DevopsWorkflows
• Azure Key Vault — DecSm.Atom.Module.AzureKeyVault
• Azure Storage — DecSm.Atom.Module.AzureStorage
• GitVersion — DecSm.Atom.Module.GitVersion

Built-in Targets

• SetupBuildInfo — Initialises build ID, version, and timestamp
• ValidateBuild — Checks the build for common issues
• GenerateWorkflowFiles — Generates CI/CD YAML files

Developer Guide

• Writing a Module — Creating a reusable Atom module NuGet package
• Custom Providers — Implementing IArtifactProvider, ISecretsProvider, and more
• Source Generators — How the Atom analysers and source generators work
• Testing — Using DecSm.Atom.TestUtils

Reference

• CLI — Command-line arguments and the Atom global tool
• API Reference — Auto-generated API documentation (via DocFX)

AI Disclaimer

The Atom libraries are human-made, however GitHub Copilot completions have been used on a superficial level.

Generative AI was also used to assist in writing tests and documentation.

License

Atom is released under the MIT License.