[GitHubActions] generator: arbitrary extra with: inputs on the checkout step

src/Fallout.Common/CI/GitHubActions/Configuration/GitHubActionsCheckoutStep.cs

@@ -24,12 +24,14 @@ public class GitHubActionsCheckoutStep : GitHubActionsStep
     /// </summary>
     public string Ref { get; set; }
 
+    public string[] CheckoutWith { get; set; } = new string[0];
+
     public override void Write(CustomFileWriter writer)
     {
         writer.WriteLine("- uses: actions/checkout@v6");
 
         if (Submodules.HasValue || Lfs.HasValue || FetchDepth.HasValue || Progress.HasValue ||
-            !Filter.IsNullOrWhiteSpace() || !Ref.IsNullOrWhiteSpace())
+            !Filter.IsNullOrWhiteSpace() || !Ref.IsNullOrWhiteSpace() || CheckoutWith.Length > 0)
         {
             using (writer.Indent())
             {
@@ -57,6 +59,9 @@ public override void Write(CustomFileWriter writer)
                         writer.WriteLine("repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}");
                         writer.WriteLine($"ref: {Ref}");
                     }
+
+                    foreach (var line in CheckoutWith)
+                        writer.WriteLine(line);
                 }
             }
         }

src/Fallout.Common/CI/GitHubActions/GitHubActionsAttribute.cs

@@ -139,6 +139,19 @@ public string CheckoutRef
         get => throw new NotSupportedException();
     }
 
+    /// <summary>
+    /// Extra <c>actions/checkout</c> inputs, emitted verbatim inside the step's <c>with:</c> block after
+    /// the typed keys (<c>submodules</c>, <c>lfs</c>, <c>fetch-depth</c>, <c>progress</c>, <c>filter</c>,
+    /// <c>ref</c>/<c>repository</c>). An escape hatch for inputs the typed knobs don't cover — <c>token</c>,
+    /// <c>ssh-key</c>, <c>path</c>, <c>clean</c>, <c>persist-credentials</c>, <c>sparse-checkout</c>,
+    /// <c>set-safe-directory</c>.
+    /// <para/>
+    /// Each entry is one raw line — passed through unvalidated, so the caller owns correct YAML. Multi-line
+    /// block scalars work by supplying the key (e.g. <c>sparse-checkout: |</c>) and each continuation line
+    /// as separate entries, with the caller's own indentation preserved. Empty emits nothing.
+    /// </summary>
+    public string[] CheckoutWith { get; set; } = new string[0];
+
     public override CustomFileWriter CreateWriter(StreamWriter streamWriter)
     {
         return new CustomFileWriter(streamWriter, indentationFactor: 2, commentPrefix: "#");
@@ -204,7 +217,8 @@ private IEnumerable<GitHubActionsStep> GetSteps(IReadOnlyCollection<ExecutableTa
                          FetchDepth = _fetchDepth,
                          Progress = _progress,
                          Filter = _filter,
-                         Ref = _ref
+                         Ref = _ref,
+                         CheckoutWith = CheckoutWith
                      };
 
         if (CacheKeyFiles.Any())

tests/Fallout.Common.Tests/CI/ConfigurationGenerationTest.Test_testName=checkout-with-only_attribute=GitHubActionsAttribute.verified.txt

@@ -0,0 +1,58 @@
+# ------------------------------------------------------------------------------
+# <auto-generated>
+#
+#     This code was generated.
+#
+#     - To turn off auto-generation set:
+#
+#         [TestGitHubActions (AutoGenerate = false)]
+#
+#     - To trigger manual generation invoke:
+#
+#         fallout --generate-configuration GitHubActions_test --host GitHubActions
+#
+# </auto-generated>
+# ------------------------------------------------------------------------------
+
+name: test
+
+on: [push]
+
+jobs:
+  ubuntu-latest:
+    name: ubuntu-latest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          path: src
+      - name: 'Cache: .fallout/temp, ~/.nuget/packages'
+        uses: actions/cache@v4
+        with:
+          path: |
+            .fallout/temp
+            ~/.nuget/packages
+          key: ${{ runner.os }}-${{ hashFiles('**/global.json', '**/*.csproj', '**/Directory.Packages.props') }}
+      - name: 'Setup: .NET SDK'
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+      - name: 'Restore: dotnet tools'
+        run: dotnet tool restore
+      - name: 'Run: Test'
+        run: dotnet fallout Test
+      - name: 'Publish: src'
+        uses: actions/upload-artifact@v5
+        with:
+          name: src
+          path: src
+      - name: 'Publish: test-results'
+        uses: actions/upload-artifact@v5
+        with:
+          name: test-results
+          path: output/test-results
+      - name: 'Publish: coverage-report.zip'
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-report.zip
+          path: output/coverage-report.zip

tests/Fallout.Common.Tests/CI/ConfigurationGenerationTest.Test_testName=checkout-with-sparse_attribute=GitHubActionsAttribute.verified.txt

@@ -0,0 +1,60 @@
+# ------------------------------------------------------------------------------
+# <auto-generated>
+#
+#     This code was generated.
+#
+#     - To turn off auto-generation set:
+#
+#         [TestGitHubActions (AutoGenerate = false)]
+#
+#     - To trigger manual generation invoke:
+#
+#         fallout --generate-configuration GitHubActions_test --host GitHubActions
+#
+# </auto-generated>
+# ------------------------------------------------------------------------------
+
+name: test
+
+on: [push]
+
+jobs:
+  ubuntu-latest:
+    name: ubuntu-latest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            src
+            build
+      - name: 'Cache: .fallout/temp, ~/.nuget/packages'
+        uses: actions/cache@v4
+        with:
+          path: |
+            .fallout/temp
+            ~/.nuget/packages
+          key: ${{ runner.os }}-${{ hashFiles('**/global.json', '**/*.csproj', '**/Directory.Packages.props') }}
+      - name: 'Setup: .NET SDK'
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+      - name: 'Restore: dotnet tools'
+        run: dotnet tool restore
+      - name: 'Run: Test'
+        run: dotnet fallout Test
+      - name: 'Publish: src'
+        uses: actions/upload-artifact@v5
+        with:
+          name: src
+          path: src
+      - name: 'Publish: test-results'
+        uses: actions/upload-artifact@v5
+        with:
+          name: test-results
+          path: output/test-results
+      - name: 'Publish: coverage-report.zip'
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-report.zip
+          path: output/coverage-report.zip

tests/Fallout.Common.Tests/CI/ConfigurationGenerationTest.Test_testName=checkout-with_attribute=GitHubActionsAttribute.verified.txt

@@ -0,0 +1,61 @@
+# ------------------------------------------------------------------------------
+# <auto-generated>
+#
+#     This code was generated.
+#
+#     - To turn off auto-generation set:
+#
+#         [TestGitHubActions (AutoGenerate = false)]
+#
+#     - To trigger manual generation invoke:
+#
+#         fallout --generate-configuration GitHubActions_test --host GitHubActions
+#
+# </auto-generated>
+# ------------------------------------------------------------------------------
+
+name: test
+
+on: [push]
+
+jobs:
+  ubuntu-latest:
+    name: ubuntu-latest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.CI_PAT }}
+          path: src
+          persist-credentials: false
+      - name: 'Cache: .fallout/temp, ~/.nuget/packages'
+        uses: actions/cache@v4
+        with:
+          path: |
+            .fallout/temp
+            ~/.nuget/packages
+          key: ${{ runner.os }}-${{ hashFiles('**/global.json', '**/*.csproj', '**/Directory.Packages.props') }}
+      - name: 'Setup: .NET SDK'
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+      - name: 'Restore: dotnet tools'
+        run: dotnet tool restore
+      - name: 'Run: Test'
+        run: dotnet fallout Test
+      - name: 'Publish: src'
+        uses: actions/upload-artifact@v5
+        with:
+          name: src
+          path: src
+      - name: 'Publish: test-results'
+        uses: actions/upload-artifact@v5
+        with:
+          name: test-results
+          path: output/test-results
+      - name: 'Publish: coverage-report.zip'
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-report.zip
+          path: output/coverage-report.zip

tests/Fallout.Common.Tests/CI/ConfigurationGenerationTest.cs

@@ -212,6 +212,55 @@ public class TestBuild : FalloutBuild
                 }
             );
 
+            // Ordering guard: extra CheckoutWith inputs emit verbatim inside the with: block, after
+            // every typed key (here fetch-depth) and in the order supplied.
+            yield return
+            (
+                "checkout-with",
+                new TestGitHubActionsAttribute(GitHubActionsImage.UbuntuLatest)
+                {
+                    On = new[] { GitHubActionsTrigger.Push },
+                    InvokedTargets = new[] { nameof(Test) },
+                    FetchDepth = 0,
+                    CheckoutWith = new[]
+                                   {
+                                       "token: ${{ secrets.CI_PAT }}",
+                                       "path: src",
+                                       "persist-credentials: false"
+                                   }
+                }
+            );
+
+            // Guard: CheckoutWith with no typed checkout key must still open the with: block.
+            yield return
+            (
+                "checkout-with-only",
+                new TestGitHubActionsAttribute(GitHubActionsImage.UbuntuLatest)
+                {
+                    On = new[] { GitHubActionsTrigger.Push },
+                    InvokedTargets = new[] { nameof(Test) },
+                    CheckoutWith = new[] { "path: src" }
+                }
+            );
+
+            // Multi-line block scalar: the case a 'KEY: value' validator would reject. Proves raw
+            // verbatim emission preserves the caller-supplied continuation lines and indentation.
+            yield return
+            (
+                "checkout-with-sparse",
+                new TestGitHubActionsAttribute(GitHubActionsImage.UbuntuLatest)
+                {
+                    On = new[] { GitHubActionsTrigger.Push },
+                    InvokedTargets = new[] { nameof(Test) },
+                    CheckoutWith = new[]
+                                   {
+                                       "sparse-checkout: |",
+                                       "  src",
+                                       "  build"
+                                   }
+                }
+            );
+
             yield return
             (
                 null,