Add a typed step-injection pipeline to the GitHub Actions generator

[avidenic]

Closes #456.

Problem

GitHubActionsAttribute.GetSteps() yields a fixed, closed step sequence with no hook points and is private. No way to inject a marketplace action or custom shell step at a chosen position.

Outcome

A build implements IConfigureGitHubActions.ConfigureSteps(GitHubActionsStepPipeline) to inject typed uses:/run: steps at four named positions — compile-checked, no reflection.

partial class Build : NukeBuild, IConfigureGitHubActions
{
    public void ConfigureSteps(GitHubActionsStepPipeline pipeline)
    {
        if (pipeline.WorkflowName != "security") return;   // scope by workflow / runner
        pipeline.Insert(GitHubActionsStepPosition.PostRun, new GitHubActionsCustomStep
        {
            Name = "Perform CodeQL Analysis",
            Uses = "github/codeql-action/analyze@v3",
            If = "github.ref == 'refs/heads/main'",
        });
    }
}

New public types: GitHubActionsCustomStep, GitHubActionsStepPosition (PostCheckout/PreRun/PostRun/JobEnd), IConfigureGitHubActions, GitHubActionsStepPipeline.

Notes

• Positions anchor to the always-present checkout + run block, so they resolve whether or not cache/artifacts are present.
• Validation fails the build (never emits invalid YAML): exactly one of Uses/Run; With requires Uses; Shell only on a run step.
• Additive / non-breaking. Generator stays in sole control of the base sequence; the hook only inserts.
• The hook is invoked per job with identity on the pipeline context (not the interface signature) and a read-only BuiltInSteps view — deliberately composes with the [GitHubActions] generator: emit CD pipelines (or a thin shell delegating to dotnet fallout Deploy) #336 job-DAG work rather than being reworked by it. Job-level concerns (needs:/outputs:/env gates) are out of scope for [GitHubActions] generator: emit CD pipelines (or a thin shell delegating to dotnet fallout Deploy) #336.
• New API follows the subsystem's existing idioms; matched to [GitHubActionsInput]'s validation style.

Acceptance criteria

• Inject uses:/run: at each of the four positions; multiple inserts at one position render in call order.
• Positions resolve correctly with cache/artifacts absent.
• Invalid steps fail generation with a clear ArgumentException.
• Steps scope to a workflow/runner via WorkflowName/Image (no per-step scoping arrays).
• No churn on existing snapshots.

Verification

Full Fallout.Common.Specs suite: 114 passed, 7 skipped, 0 failed. Zero snapshot churn. Full-solution build clean.

[ChrisonSimtian]

nice feature, thanks for bringing this in :-)

[ChrisonSimtian]

Really clean, additive design — the generator keeps sole control of the base sequence and the hook only inserts. Test coverage is the standout: all four positions, the cache/artifacts-absent anchoring case, ordering, workflow scoping, and a byte-identical no-op regression guard.

Approving — nothing here blocks, but one is worth fixing before this gets real-world use (inline): custom-step scalar values are emitted unquoted, whereas every built-in step quotes names, so a Name/If/Uses containing a colon-space, #, or leading indicator char emits invalid YAML. That contradicts the "never emits invalid YAML" line, which today only covers the structural uses/run checks. Two smaller notes on dictionary ordering and a null-step guard.

Confirmed Assert.True throws ArgumentException (src/Fallout.Utilities/Assert.cs), so the validation specs assert the right type. 👍

[Copilot]

Pull request overview

Adds a public, typed step-injection hook to the GitHub Actions generator so builds can insert custom uses: / run: steps at fixed, named positions per job, while keeping the generator’s base step sequence intact.

Changes:

• Introduces the step-injection API surface (IConfigureGitHubActions, GitHubActionsStepPipeline, GitHubActionsCustomStep, GitHubActionsStepPosition).
• Extends GitHubActionsAttribute generation to invoke the hook per job, validate injected steps, and splice inserts into the rendered step list.
• Adds specs + snapshot coverage for ordering, anchor positions (with/without cache/artifacts), scoping via pipeline context, and validation failures.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Fallout.Common.Specs/CI/GitHubActionsStepPipelineSpecs.cs	Unit coverage for pipeline context exposure + insertion ordering semantics.
tests/Fallout.Common.Specs/CI/GitHubActionsStepInjectionSpecs.cs	Behavioral coverage of injection positions, ordering, scoping, and no-op regression.
tests/Fallout.Common.Specs/CI/GitHubActionsStepInjectionSpecs.Rich_injection_renders_expected_yaml.verified.txt	Snapshot contract for rich multi-position injection YAML output.
tests/Fallout.Common.Specs/CI/GitHubActionsCustomStepValidationSpecs.cs	Verifies invalid injected steps fail generation with ArgumentException.
tests/Fallout.Common.Specs/CI/GitHubActionsCustomStepSpecs.cs	Isolated rendering specs for GitHubActionsCustomStep YAML output.
src/Fallout.Common/Fallout.Common.csproj	Adds InternalsVisibleTo for specs to access internal pipeline APIs.
src/Fallout.Common/CI/GitHubActions/IConfigureGitHubActions.cs	New build hook interface invoked per generated job.
src/Fallout.Common/CI/GitHubActions/GitHubActionsStepPosition.cs	New enum defining the four named insertion anchors.
src/Fallout.Common/CI/GitHubActions/GitHubActionsAttribute.cs	Hook invocation + splice/validation integrated into job step generation.
src/Fallout.Common/CI/GitHubActions/Configuration/GitHubActionsStepPipeline.cs	Pipeline implementation collecting inserts and exposing built-in steps context.
src/Fallout.Common/CI/GitHubActions/Configuration/GitHubActionsCustomStep.cs	New user-constructible step type for uses:/run: with optional fields + YAML writer.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ITaluone]

Nice work!

Just this two questions

[ITaluone]

Very nice work!

Thanks again