The Generated API Surface and Fluent Builder📋

var result = await new GitLabCiFileBuilder()
    .WithStages(new List<object> { "build", "test", "deploy" })
    .WithVariables(new Dictionary<string, object?>
    {
        ["DOTNET_VERSION"] = "9.0",
        ["CONFIGURATION"] = "Release"
    })
    .WithJob("build", job => job
        .WithImage("mcr.microsoft.com/dotnet/sdk:9.0")
        .WithScript(new List<string>
        {
            "dotnet restore",
            "dotnet build -c $CONFIGURATION"
        })
        .WithArtifacts(new GitLabCiArtifacts
        {
            Paths = new List<string> { "bin/", "obj/" }
        }))
    .WithJob("test", job => job
        .WithImage("mcr.microsoft.com/dotnet/sdk:9.0")
        .WithScript(new List<string> { "dotnet test --logger trx" })
        .WithArtifacts(new GitLabCiArtifacts
        {
            Reports = new GitLabCiArtifactsReports
            {
                Junit = new List<string> { "junit.xml" },
                CoverageReport = new List<string> { "coverage/cobertura.xml" }
            }
        }))
    .BuildAsync();

var ciFile = result.ValueOrThrow().Resolved();

builder.WithVariables(vars => vars
    .With("NODE_ENV", "production")
    .With("DOCKER_TLS_CERTDIR", "")
    .With("CI_DEBUG_TRACE", "false"))

builder
    .WithJob("build", job => job
        .WithImage("node:20")
        .WithScript(new List<string> { "npm ci", "npm run build" }))
    .WithJob("test", job => job
        .WithScript(new List<string> { "npm test" })
        .WithArtifacts(new GitLabCiArtifacts
        {
            Reports = new GitLabCiArtifactsReports
            {
                Junit = new List<string> { "test-results.xml" }
            }
        }))
    .WithJob("deploy", job => job
        .WithScript(new List<string> { "echo Deploying..." })
        .WithWhen("manual")
        .WithEnvironment(new GitLabCiJobTemplateEnvironmentConfig
        {
            Name = "production",
            Url = "https://app.example.com"
        }))

public class StrictPipelineBuilder : GitLabCiFileBuilder
{
    protected override IEnumerable<Exception>? ValidateStages(
        List<object>? value)
    {
        if (value is null || value.Count == 0)
            yield return new InvalidOperationException(
                "Pipeline must define at least one stage.");
    }

    protected override IEnumerable<Exception>? ValidateJobs(
        Dictionary<string, GitLabCiJob>? value)
    {
        if (value is null || value.Count == 0)
            yield return new InvalidOperationException(
                "Pipeline must define at least one job.");
    }
}

var result = await new StrictPipelineBuilder()
    .WithStages(new List<object>()) // Empty — will fail validation
    .BuildAsync();

if (!result.IsSuccess)
{
    foreach (var error in result.Errors)
        Console.WriteLine($"Validation error: {error}");
}
else
{
    var ciFile = result.ValueOrThrow().Resolved();
    var yaml = GitLabCiYamlWriter.Serialize(ciFile);
}