👁 Image
Invex.Atom.Module.GithubWorkflows 3.1.0

Atom

👁 Validate
👁 Build
👁 Dependabot Updates

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.

Examples

Hello World

1. Create a .NET 10 project

   dotnet new console -n _atom
   

2. Update the _atom.csproj file:

   <Project Sdk="Microsoft.NET.Sdk.Worker">
   
    <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <RootNamespace>Atom</RootNamespace>
    </PropertyGroup>
   
    <ItemGroup>
    <PackageReference Include="Invex.Atom.Build" Version="3.*" />
    </ItemGroup>
   
   </Project>
   

3. Replace the Program.cs file with IBuild.cs:

   using Invex.Atom.Build.Definition;
   using Invex.Atom.Build.Hosting;
   
   namespace Atom;
   
   [BuildDefinition]
   [GenerateEntryPoint]
   internal interface IBuild : IBuildDefinition
   {
    Target HelloWorld =>
    t => t
    .DescribedAs("Prints a hello world message to the console")
    .Executes(() => Logger.LogInformation("Hello, World!"));
   }
   

4. Execute atom HelloWorld

   26-06-06 +10:00 Invex.Atom.Build.BuildExecutor:
   01:16:47.552 INF Executing build
   
   HelloWorld
   
   Prints a hello world message to the console
   
   26-06-06 +10:00 HelloWorld | Atom.Build: 
   01:16:47.616 INF Hello, World!
   
   
   Build Summary
   
   HelloWorld │ Succeeded │ <0.01s
   

Adding Params

1. Add a parameter to the IBuild interface:

   .RequiresParam(nameof(...)) is used to ensure the parameter is provided before the target is executed.

   .UsesParam(nameof(...)) is used to use the parameter if it is provided, but not fail the build if it is not.

   using Invex.Atom.Build.Definition;
   using Invex.Atom.Build.Hosting;
   using Invex.Atom.Build.Params;
   
   namespace Atom;
   
   [BuildDefinition]
   [GenerateEntryPoint]
   internal interface IBuild : IBuildDefinition
   {
    [ParamDefinition("my-name", "My name")]
    string? MyName => GetParam(() => MyName);
   
    Target HelloWorld =>
    t => t
    .DescribedAs("Prints a hello world message to the console")
    .RequiresParam(nameof(MyName))
    .Executes(() => Logger.LogInformation("Hello, World! I am {MyName}.", MyName));
   }
   

2. Execute `atom HelloWorld --my-name Frodo

   26-06-06 +10:00 Invex.Atom.Build.BuildExecutor:
   01:23:25.405 INF Executing build
   
   HelloWorld
   
   Prints a hello world message to the console
   
   26-06-06 +10:00 HelloWorld | Atom.Build:
   01:23:25.467 INF Hello, World! I am Frodo.
   
   
   Build Summary
   
    HelloWorld │ Succeeded │ <0.01s
   

Adding Secrets

1. Add a secret parameter to the IBuild interface:

   using Invex.Atom.Build.Definition;
   using Invex.Atom.Build.Hosting;
   using Invex.Atom.Build.Params;
   
   namespace Atom;
   
   [BuildDefinition]
   [GenerateEntryPoint]
   internal interface IBuild : IBuildDefinition
   {
    [ParamDefinition("my-name", "My name")]
    string? MyName => GetParam(() => MyName);
   
    [SecretDefinition("my-secret", "My secret")]
    string? MySecret => GetParam(() => MySecret);
   
    Target HelloWorld =>
    t => t
    .DescribedAs("Prints a hello world message to the console")
    .RequiresParam(nameof(MyName))
    .RequiresParam(nameof(MySecret))
    .Executes(() =>
    Logger.LogInformation("Hello, World! I am {MyName} and my secret is {MySecret}.",
    MyName,
    MySecret));
   }
   

2. Execute atom HelloWorld --my-name Frodo --my-secret TheOneRing

   The secret is masked in the output.

   26-06-06 +10:00 Invex.Atom.Build.BuildExecutor:
   01:27:08.482 INF Executing build 
   
   HelloWorld
   
   Prints a hello world message to the console
   
   26-06-06 +10:00 HelloWorld | Atom.Build: 
   01:27:08.544 INF Hello, World! I am Frodo and my secret is *****.
   
   
   Build Summary
   
    HelloWorld │ Succeeded │ <0.01s
   

Adding Target Dependencies

1. Update the IBuild interface:

   using Invex.Atom.Build.Definition;
   using Invex.Atom.Build.Hosting;
   using Invex.Atom.Build.Params;
   
   namespace Atom;
   
   [BuildDefinition]
   [GenerateEntryPoint]
   internal interface IBuild : IBuildDefinition
   {
    [ParamDefinition("my-name", "My name")]
    string? MyName => GetParam(() => MyName);
   
    [SecretDefinition("my-secret", "My secret")]
    string? MySecret => GetParam(() => MySecret);
   
    Target HelloWorld =>
    t => t
    .DescribedAs("Prints a hello world message to the console")
    .RequiresParam(nameof(MyName))
    .RequiresParam(nameof(MySecret))
    .Executes(() =>
    Logger.LogInformation("Hello, World! I am {MyName} and my secret is {MySecret}.", MyName, MySecret));
   
    Target Goodbye =>
    t => t
    .DescribedAs("Prints a goodbye message to the console")
    .DependsOn(nameof(HelloWorld))
    .Executes(() => Logger.LogInformation("Goodbye!"));
   }
   

2. Execute atom Goodbye --my-name Frodo --my-secret TheOneRing

   The Goodbye target depends on the HelloWorld target, so both will be executed in the correct order, and the parameters only need to be provided once.

   26-06-06 +10:00 Invex.Atom.Build.BuildExecutor:
   01:30:12.175 INF Executing build 
   
   HelloWorld
   
   Prints a hello world message to the console
   
   26-06-06 +10:00 HelloWorld | Atom.Build: 
   01:30:12.235 INF Hello, World! I am Frodo and my secret is *****.
   
   Goodbye
   
   Prints a goodbye message to the console
   
   26-06-06 +10:00 Goodbye | Atom.Build:
   01:30:12.240 INF Goodbye! 
   
   
   Build Summary
   
    HelloWorld │ Succeeded │ <0.01s 
    Goodbye │ Succeeded │ <0.01s
   

Adding Workflow Generation

1. Update the _atom.csproj file:

   <Project Sdk="Microsoft.NET.Sdk.Worker">
   
    <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <RootNamespace>Atom</RootNamespace>
    </PropertyGroup>
   
    <ItemGroup>
    <PackageReference Include="Invex.Atom.Module.GithubWorkflows" Version="3.*" />
    </ItemGroup>
   
   </Project>
   

2. Update the IBuild interface:

   using Invex.Atom.Build.BuildOptions;
   using Invex.Atom.Build.Definition;
   using Invex.Atom.Build.Hosting;
   using Invex.Atom.Build.Params;
   using Invex.Atom.Module.GithubWorkflows.Extensions;
   using Invex.Atom.Module.GithubWorkflows.Helpers;
   using Invex.Atom.Workflows;
   using Invex.Atom.Workflows.Definition;
   using Invex.Atom.Workflows.Definition.Triggers;
   using Invex.Atom.Workflows.Options;
   using Invex.StructuredText.Expressions;
   
   namespace Atom;
   
   [BuildDefinition]
   [GenerateEntryPoint]
   internal interface IBuild : IWorkflowBuildDefinition, IGithubWorkflows
   {
   [ParamDefinition("my-name", "My name")]
   string? MyName => GetParam(() => MyName);
   
    [SecretDefinition("my-secret", "My secret")]
    string? MySecret => GetParam(() => MySecret);
   
    Target HelloWorld =>
    t => t
    .DescribedAs("Prints a hello world message to the console")
    .RequiresParam(nameof(MyName))
    .RequiresParam(nameof(MySecret))
    .Executes(() =>
    Logger.LogInformation("Hello, World! I am {MyName} and my secret is {MySecret}.", MyName, MySecret));
   
    Target Goodbye =>
    t => t
    .DescribedAs("Prints a goodbye message to the console")
    .DependsOn(nameof(HelloWorld))
    .Executes(() => Logger.LogInformation("Goodbye!"));
   
    IReadOnlyList<WorkflowDefinition> IWorkflowBuildDefinition.Workflows =>
    [
    new("Hello")
    {
    Triggers = [WorkflowTriggers.PushToMain],
    Targets =
    [
    new(nameof(HelloWorld))
    {
    Options =
    [
    BuildOptions.Inject.Param(nameof(MyName), TextExpressions.Github.GithubRepositoryOwner),
    BuildOptions.Inject.Secret(nameof(MySecret)),
    ],
    },
    new(nameof(Goodbye)),
    ],
    Types = [WorkflowTypes.Github.Action],
    },
    ];
   }
   

3. Execute atom gen

   26-06-06 +10:00 Invex.Atom.Module.GithubWorkflows.GithubActions.GithubWorkflowFileWriter: 
   01:38:57.388 INF Writing new workflow file: 
    L:\Repos\Invex-Games\atom\.github\workflows\Hello.yml 
   
   
   26-06-06 +10:00 Invex.Atom.Build.BuildExecutor:
   01:38:57.472 INF Executing build 
   
   Gen
   
   Generates workflow files
   
   
   Build Summary
   
    Gen │ Succeeded │ <0.01s
   

   .github/workflows/Hello.yml

   name: Hello
   
   on:
    push:
    branches: [ main ]
   
   permissions: { }
   
   jobs:
   
    HelloWorld:
    runs-on: ubuntu-latest
    steps:
   
    - name: Checkout
    uses: actions/checkout@v6
    with:
    fetch-depth: 0
   
    - name: HelloWorld
    id: HelloWorld
    run: dotnet run --project _atom/_atom.csproj -- HelloWorld --skip --headless
    env:
    my-secret: ${{ secrets.MY_SECRET }}
    my-name: ${{ github.repository_owner }}
   
    Goodbye:
    needs: [ HelloWorld ]
    runs-on: ubuntu-latest
    steps:
   
    - name: Checkout
    uses: actions/checkout@v6
    with:
    fetch-depth: 0
   
    - name: Goodbye
    id: Goodbye
    run: dotnet run --project _atom/_atom.csproj -- Goodbye --skip --headless
   

File-based Apps

Atom can also be used as a file-based app:

Atom.cs

#:sdk Microsoft.NET.Sdk.Worker
#:package Invex.Atom.Build@3.*

using Invex.Atom.Build.Definition;
using Invex.Atom.Build.Hosting;

namespace Atom;

[BuildDefinition]
[GenerateEntryPoint]
internal interface IBuild : IBuildDefinition
{
 Target HelloWorld =>
 t => t
 .DescribedAs("Prints a hello world message to the console")
 .Executes(() => Logger.LogInformation("Hello, World!"));
}

Documentation

Getting Started

• — What Atom is and why you'd use it
• — Create a minimal build and run it
• — BuildDefinition vs WorkflowBuildDefinition

Core Concepts

• — The [BuildDefinition] attribute and source generators
• — Defining targets with the fluent TargetDefinition API
• — Declaring, requiring, and resolving parameters
• — Secure parameter handling with ISecretsProvider
• — Producing and consuming build artifacts
• — Sharing data between targets with workflow variables
• — IRootedFileSystem, RootedPath, and path providers
• — Executing external processes
• — Build ID, version, and timestamp providers
• — Configuring build behaviour with IBuildOption
• — AtomHost, [GenerateEntryPoint], and host configuration
• — IAtomLifecycleHook for pre/post-build logic
• — Spectre console output and report data
• — Temporary, reversible file edits with TransformFileScope

Workflows

• — What workflows add on top of a base build
• — WorkflowDefinition, targets, and types
• — Push, pull request, and manual triggers
• — Checkout, deployment, conditions, and more
• — Cross-job data sharing
• — Local workflow simulation

Modules

• — What a module is and how to add one
• — Invex.Atom.Module.Dotnet
• — Invex.Atom.Module.GithubWorkflows
• — Invex.Atom.Module.DevopsWorkflows
• — Invex.Atom.Module.AzureKeyVault
• — Invex.Atom.Module.AzureStorage
• — Invex.Atom.Module.GitVersion

Built-in Targets

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

Developer Guide

• — Creating a reusable Atom module NuGet package
• — Implementing IArtifactProvider, ISecretsProvider, and more
• — How the Atom analysers and source generators work
• — Using Invex.Atom.TestUtils

Reference

• — Command-line arguments and the Atom global tool
• — 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 .