Invex.Atom.Module.GithubWorkflows 4.0.0-rc.23

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.

Packages

Features

• Zero context switching. Write build logic in C# alongside your application code.
• IntelliSense and debugging. Step through your build process using your IDE.
• CI/CD agnostic. Define logic once; Atom generates the YAML for GitHub Actions and Azure DevOps.
• Modular. Pull in capabilities via NuGet packages (GitVersion, Azure Key Vault, and more).
• Source generators. Targets and parameters are discovered automatically, so there is no registration boilerplate.

Installation

Atom build projects require the .NET 10 SDK. The libraries target net10.0.

Add the core package to your build project (commonly _atom/_atom.csproj):

dotnet add package Invex.Atom.Build

Install the CLI once if you want to invoke builds from any directory:

dotnet tool install --global Invex.Atom.Tool

Quick start

1. Create a .NET 10 project:

   dotnet new console -n _atom
   

2. Replace the contents of _atom.csproj:

   <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 Program.cs 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. Run the target with atom HelloWorld (or dotnet run --project _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
   

Usage

Parameters and secrets

Declare a parameter with [ParamDefinition] (or a secret with [SecretDefinition], which is masked in logs) and require it on a target:

[ParamDefinition("my-name", "My name")]
string? MyName => GetParam(() => MyName);

[SecretDefinition("my-secret", "My secret")]
string? MySecret => GetParam(() => MySecret);

Target HelloWorld =>
    t => t
        .RequiresParam(nameof(MyName))
        .RequiresParam(nameof(MySecret))
        .Executes(() => Logger.LogInformation("I am {MyName} and my secret is {MySecret}.", MyName, MySecret));

Run it with atom HelloWorld --my-name Frodo --my-secret TheOneRing. See Parameters and Secrets.

Target dependencies

Targets run in dependency order, and parameters only need to be provided once:

Target Goodbye =>
    t => t
        .DescribedAs("Prints a goodbye message to the console")
        .DependsOn(nameof(HelloWorld))
        .Executes(() => Logger.LogInformation("Goodbye!"));

atom Goodbye --my-name Frodo --my-secret TheOneRing runs HelloWorld and then Goodbye. See Targets.

Workflow generation

Reference Invex.Atom.Module.GithubWorkflows, extend IWorkflowBuildDefinition, and declare a workflow:

using Invex.StructuredText.Expressions;

[BuildDefinition]
[GenerateEntryPoint]
internal interface IBuild : IWorkflowBuildDefinition, IGithubWorkflows
{
    // targets and parameters as above

    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],
        },
    ];
}

atom Gen writes .github/workflows/Hello.yml, with one job per target and the parameter and secret injected from GitHub. See Workflow Definitions.

File-based apps

A build can also be a single Atom.cs file run with dotnet run Atom.cs HelloWorld:

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

[BuildDefinition]
[GenerateEntryPoint]
internal interface IBuild : IBuildDefinition
{
    Target HelloWorld => t => t.Executes(() => Logger.LogInformation("Hello, World!"));
}

See Your First Build.

Documentation

Full documentation: https://invex-games.github.io/atom/

Development

The solution is Invex.Atom.slnx and requires the .NET 10 SDK:

dotnet build Invex.Atom.slnx
dotnet test Invex.Atom.slnx

Atom builds itself with the build definition in _atom/. Build or preview the DocFX documentation with:

atom BuildDocs
atom ServeDocs

dotnet run --project _atom -- <target> is equivalent to atom <target>.

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.