Getting Started
This page shows how to install the packages and generate your first GitHub Actions workflow, Azure DevOps pipeline, and Dependabot config. Start here if you have not used the library before.
Requirements
- .NET 10.0 or .NET 11.0
Installation
Install the package for the platform you want to target. Each platform package automatically brings in the
Invex.StructuredText core library.
# GitHub Actions workflows + Dependabot configs
dotnet add package Invex.StructuredText.GithubActions
# Azure DevOps Pipelines
dotnet add package Invex.StructuredText.AzureDevopsPipelines
# Just the core writer and expression API
dotnet add package Invex.StructuredText
The general pattern
Every generator in this library follows the same three-step pattern:
- Build a model — construct an object graph (
GithubAction,DependabotConfig, orDevopsPipeline) using records withinitproperties and collection expressions. - Write it — pass the model to the corresponding writer (
GithubActionWriter,DependabotConfigWriter, orDevopsPipelineWriter). - Get the text — call
writer.TextWriter.ToString()and save it wherever you need.
var writer = new GithubActionWriter();
writer.Write(myWorkflow);
var yaml = writer.TextWriter.ToString();
File.WriteAllText(".github/workflows/ci.yml", yaml);
Your first GitHub Actions workflow
using Invex.StructuredText.Expressions;
using Invex.StructuredText.GithubActions;
using Invex.StructuredText.GithubActions.GithubActionModel;
var workflow = new GithubAction
{
Name = "CI",
On =
[
new On.Push
{
Branches = ["main"],
BranchesIgnore = null,
Tags = null,
TagsIgnore = null,
Paths = null,
PathsIgnore = null,
},
],
Jobs =
[
new Job
{
Name = "build",
RunsOn = new() { Labels = ["ubuntu-latest"] },
Steps =
[
new Step.UsesStep { Name = "Checkout", Uses = "actions/checkout@v6" },
new Step.RunStep
{
Name = "Build",
If = Tex.GitHub.EventName.Eq("push"),
Run = [$"dotnet build -c Release -p:Version=1.0.{Tex.GitHub.RunNumber}"],
},
],
},
],
};
var writer = new GithubActionWriter();
writer.Write(workflow);
Console.WriteLine(writer.TextWriter.ToString());
Output:
name: CI
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Build
if: github.event_name == 'push'
run: 'dotnet build -c Release -p:Version=1.0.${{ github.run_number }}'
Plain strings are written as they are. Tex.GitHub.EventName.Eq("push") is a typed condition, and the interpolated
Run line embeds github.run_number as an expression. Everything that creates an expression starts with Tex., so
IntelliSense on Tex. is the quickest way to find what you need. See Expressions.
Your first Azure DevOps pipeline
using Invex.StructuredText.AzureDevopsPipelines;
using Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Pipeline;
using Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Steps;
using Invex.StructuredText.AzureDevopsPipelines.DevopsPipelineModel.Triggers;
using Invex.StructuredText.Expressions;
var pipeline = new DevopsPipeline.DevopsPipelineWithSteps
{
Trigger = new Trigger.BranchList { Branches = ["main"] },
Steps =
[
new Step.Script
{
ScriptContent = $"echo Building {Tex.DevOps.Build.SourceBranchName}",
DisplayName = "Say hello",
},
],
};
var writer = new DevopsPipelineWriter();
writer.Write(pipeline);
Console.WriteLine(writer.TextWriter.ToString());
Output:
trigger:
branches:
include: [ main ]
steps:
- script: echo Building $(Build.SourceBranchName)
displayName: Say hello
Your first Dependabot config
using Invex.StructuredText.GithubActions;
using Invex.StructuredText.GithubActions.DependabotConfigModel.Model;
var config = new DependabotConfig
{
Updates =
[
new DependabotUpdate
{
PackageEcosystem = "nuget",
Directory = "/",
Schedule = new() { Interval = ScheduleInterval.Weekly },
},
],
};
var writer = new DependabotConfigWriter();
writer.WriteConfig(config);
File.WriteAllText(".github/dependabot.yml", writer.TextWriter.ToString());
A common workflow: generate-and-commit
A typical setup is a small console project in your repository (e.g. _build/ or _atom/) that regenerates all
workflow files. Run it locally or in CI, then commit the output. Because generation is deterministic, the diff shows
exactly what changed.
// Program.cs in a build-tool project
var writer = new GithubActionWriter();
writer.Write(BuildCiWorkflow());
File.WriteAllText("../.github/workflows/ci.yml", writer.TextWriter.ToString());
writer = new GithubActionWriter(); // fresh writer per file
writer.Write(BuildReleaseWorkflow());
File.WriteAllText("../.github/workflows/release.yml", writer.TextWriter.ToString());
Note
Writers accumulate text in an internal StructuredTextWriter. Use a fresh writer per output file, or call
writer.TextWriter.Reset() between writes.
Next steps
- Expressions: conditions, references and interpolated values
- GitHub Actions Workflows: the full workflow model
- Azure DevOps Pipelines: stages, jobs, deployment strategies, resources
- Dependabot Configuration: registries, groups, schedules
- FAQ: common questions and troubleshooting
- API: GithubActionWriter, DependabotConfigWriter, DevopsPipelineWriter