Make the generated action references configurable

.github/workflows/build-cross-platform.yml

@@ -42,7 +42,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: 'Cache: .fallout/temp, ~/.nuget/packages'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: |
             .fallout/temp
@@ -64,7 +64,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: 'Cache: .fallout/temp, ~/.nuget/packages'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: |
             .fallout/temp

.github/workflows/build.yml

@@ -42,7 +42,7 @@ jobs:
           repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
           ref: ${{ github.head_ref }}
       - name: 'Cache: .fallout/temp, ~/.nuget/packages'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: |
             .fallout/temp

.github/workflows/publish-packages-preview.yml

@@ -53,7 +53,7 @@ jobs:
         with:
           fetch-depth: 0           # Nerdbank.GitVersioning needs full history
       - name: 'Cache: .fallout/temp, ~/.nuget/packages'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: |
             .fallout/temp

.github/workflows/publish-packages-release.yml

@@ -102,7 +102,7 @@ jobs:
           ref: ${{ inputs.tag || github.ref }}
           fetch-depth: 0           # Nerdbank.GitVersioning needs full history
       - name: 'Cache: .fallout/temp, ~/.nuget/packages'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: |
             .fallout/temp

docs/05-cicd/github-actions.md

@@ -208,7 +208,7 @@ By default, the generated workflow file will include a [caching step](https://gi
 
 ```yaml title=".github/workflows/continuous.yml"
 - name: 'Cache: .fallout/temp, ~/.nuget/packages'
-  uses: actions/cache@v4
+  uses: actions/cache@v6
   with:
     path: |
       .fallout/temp
@@ -228,3 +228,38 @@ You can customize the caching step by overwriting the following properties:
     CacheExcludePatterns = new string[0])]
 class Build : FalloutBuild { /* ... */ }
 ```
+
+### Pinning Action Versions
+
+The generated workflow references four marketplace actions. Each one is overridable, so a new action release never has to wait on a Fallout release:
+
+| Property | Action | Default |
+| --- | --- | --- |
+| `CheckoutAction` | [`actions/checkout`](https://github.com/actions/checkout) | `v7` |
+| `CacheAction` | [`actions/cache`](https://github.com/actions/cache) | `v6` |
+| `SetupDotNetAction` | [`actions/setup-dotnet`](https://github.com/actions/setup-dotnet) | `v6` |
+| `UploadArtifactAction` | [`actions/upload-artifact`](https://github.com/actions/upload-artifact) | `v7` |
+
+A value containing an `@` is a complete reference and is emitted as-is; anything else is a bare ref and gets appended to the default action:
+
+```csharp title="Build.cs"
+[GitHubActions(
+    // ...
+    CheckoutAction = "v8",                                                   // actions/checkout@v8
+    CacheAction = "0c907a75c2c80ebcb7f088228285e798b750cf8f # v4.2.4",       // SHA pin, version as comment
+    UploadArtifactAction = "my-org/upload-artifact@v7")]                     // fork or drop-in replacement
+class Build : FalloutBuild { /* ... */ }
+```
+
+Both forms take a trailing `# comment`, which is what makes the [SHA-pinning](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) idiom above readable. The comment is split off before the value is classified, so a slash or an `@` inside it changes nothing.
+
+A ref that itself contains a `/` — a branch like `releases/v1` — reads exactly like an `owner/repo`, so it needs a leading `@` to disambiguate:
+
+```csharp
+CheckoutAction = "@releases/v1"     // actions/checkout@releases/v1
+CheckoutAction = "releases/v1"      // error: ambiguous, names neither form
+```
+
+:::note
+`actions/cache@v5` and later run on the node24 runtime and require a self-hosted runner of at least `2.327.1`. Set `CacheAction = "v4"` if your runners are older.
+:::

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

@@ -0,0 +1,103 @@
+using System;
+using System.Linq;
+using Fallout.Common.Utilities;
+
+namespace Fallout.Common.CI.GitHubActions.Configuration;
+
+/// <summary>
+/// Resolves a user-supplied action override against the version the generator pins by default.
+/// </summary>
+internal static class GitHubActionsActionReference
+{
+    /// <summary>
+    /// Resolves <paramref name="value"/> into the <c>uses:</c> value to emit. A trailing <c># comment</c> is
+    /// split off first and never taken into account when classifying, so a commit pin commented with a
+    /// version or a URL behaves like any other reference. What remains is then read as:
+    /// <list type="bullet">
+    /// <item>null or whitespace — falls back to <paramref name="defaultAction"/>.</item>
+    /// <item>contains an <c>@</c> — a complete reference, emitted verbatim (<c>my-org/checkout@v9</c>,
+    /// <c>actions/checkout@11bd7190…</c>).</item>
+    /// <item>starts with <c>@</c>, or contains no <c>/</c> — a bare ref appended to
+    /// <paramref name="defaultAction"/>'s <c>owner/repo</c>, so <c>v8</c> becomes <c>actions/checkout@v8</c>
+    /// and <c>@releases/v1</c> becomes <c>actions/checkout@releases/v1</c>.</item>
+    /// <item>contains a <c>/</c> but no <c>@</c> — ambiguous between the two (a fork missing its version
+    /// reads exactly like a branch ref), and rejected rather than guessed at.</item>
+    /// </list>
+    /// Local (<c>./path</c>) and container (<c>docker://</c>) references are passed through as-is.
+    /// </summary>
+    public static string Resolve(string defaultAction, string value)
+    {
+        if (value.IsNullOrWhiteSpace())
+            return defaultAction;
+
+        Assert.True(value.All(x => !char.IsControl(x)),
+            $"Action reference '{value}' must be a single line without control characters");
+
+        var (reference, comment) = SplitComment(value.Trim());
+
+        Assert.True(!reference.IsNullOrWhiteSpace(),
+            $"Action reference '{value}' is only a comment and names no action");
+        // The reference is emitted into an unquoted YAML scalar, where whitespace would let a second key
+        // (': ') or a stray token through and corrupt the whole workflow file.
+        Assert.True(reference.All(x => !char.IsWhiteSpace(x)),
+            $"Action reference '{reference}' must not contain whitespace — expected 'owner/repo@ref' or a bare ref");
+
+        if (!reference.StartsWith("./", StringComparison.Ordinal) &&
+            !reference.StartsWith("docker://", StringComparison.Ordinal))
+        {
+            reference = ResolveActionReference(defaultAction, reference);
+        }
+
+        return comment == null ? reference : $"{reference} {comment}";
+    }
+
+    private static string ResolveActionReference(string defaultAction, string reference)
+    {
+        // A leading '@' marks a bare ref explicitly — the only way to say that a slash-bearing value like
+        // 'releases/v1' is a branch rather than an owner/repo.
+        var isExplicitBareRef = reference.StartsWith("@", StringComparison.Ordinal);
+        if (isExplicitBareRef)
+            reference = reference.Substring(startIndex: 1);
+
+        var separatorIndex = reference.IndexOf('@');
+        if (!isExplicitBareRef && separatorIndex >= 0)
+        {
+            var name = reference.Substring(startIndex: 0, separatorIndex);
+            var gitReference = reference.Substring(separatorIndex + 1);
+
+            Assert.True(name.Contains('/'),
+                $"Action reference '{reference}' must name the action as 'owner/repo@ref'");
+            Assert.True(!gitReference.IsNullOrWhiteSpace() && !gitReference.Contains('@'),
+                $"Action reference '{reference}' must name exactly one version or commit after the '@'");
+
+            return reference;
+        }
+
+        Assert.True(!reference.IsNullOrWhiteSpace() && !reference.Contains('@'),
+            $"Action reference '{reference}' must name exactly one version or commit");
+        Assert.True(isExplicitBareRef || !reference.Contains('/'),
+            $"Action reference '{reference}' is ambiguous — write 'owner/repo@ref' for a complete reference, " +
+            $"or '@{reference}' to use it as a ref on '{GetActionName(defaultAction)}'");
+
+        return $"{GetActionName(defaultAction)}@{reference}";
+    }
+
+    private static string GetActionName(string defaultAction)
+    {
+        var separatorIndex = defaultAction.IndexOf('@');
+        return separatorIndex > 0 ? defaultAction.Substring(startIndex: 0, separatorIndex) : defaultAction;
+    }
+
+    // A '#' opens a YAML comment only at the start of the scalar or after whitespace; anywhere else it is
+    // an ordinary character and stays part of the reference.
+    private static (string Reference, string Comment) SplitComment(string value)
+    {
+        if (value.StartsWith("#", StringComparison.Ordinal))
+            return (string.Empty, value);
+
+        var commentIndex = value.IndexOf(" #", StringComparison.Ordinal);
+        return commentIndex < 0
+            ? (value, null)
+            : (value.Substring(startIndex: 0, commentIndex).TrimEnd(), value.Substring(commentIndex + 1));
+    }
+}

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

@@ -6,14 +6,27 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 
 public class GitHubActionsArtifactStep : GitHubActionsStep
 {
+    private string uses = GitHubActionsDefaults.UploadArtifactAction;
+
+    /// <summary>
+    /// The upload-artifact action to reference. Accepts a complete <c>owner/repo@ref</c> or a bare ref that
+    /// gets appended to <c>actions/upload-artifact</c>. Defaults to the version the generator pins; setting
+    /// null or whitespace restores it.
+    /// </summary>
+    public string Uses
+    {
+        set => uses = GitHubActionsActionReference.Resolve(GitHubActionsDefaults.UploadArtifactAction, value);
+        get => uses;
+    }
+
     public string Name { get; set; }
     public string Path { get; set; }
     public string Condition { get; set; }
 
     public override void Write(CustomFileWriter writer)
     {
         writer.WriteLine("- name: " + $"Publish: {Name}".SingleQuoteYaml());
-        writer.WriteLine("  uses: actions/upload-artifact@v7");
+        writer.WriteLine($"  uses: {Uses}");
 
         using (writer.Indent())
         {

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

@@ -8,6 +8,19 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 // https://github.com/actions/cache
 public class GitHubActionsCacheStep : GitHubActionsStep
 {
+    private string uses = GitHubActionsDefaults.CacheAction;
+
+    /// <summary>
+    /// The cache action to reference. Accepts a complete <c>owner/repo@ref</c> or a bare ref that gets
+    /// appended to <c>actions/cache</c>. Defaults to the version the generator pins; setting null or
+    /// whitespace restores it.
+    /// </summary>
+    public string Uses
+    {
+        set => uses = GitHubActionsActionReference.Resolve(GitHubActionsDefaults.CacheAction, value);
+        get => uses;
+    }
+
     public string[] IncludePatterns { get; set; }
     public string[] ExcludePatterns { get; set; }
     public string[] KeyFiles { get; set; }
@@ -17,7 +30,7 @@ public override void Write(CustomFileWriter writer)
         writer.WriteLine("- name: " + $"Cache: {IncludePatterns.JoinCommaSpace()}".SingleQuoteYaml());
         using (writer.Indent())
         {
-            writer.WriteLine("uses: actions/cache@v4");
+            writer.WriteLine($"uses: {Uses}");
             writer.WriteLine("with:");
             using (writer.Indent())
             {

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

@@ -6,6 +6,19 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 
 public class GitHubActionsCheckoutStep : GitHubActionsStep
 {
+    private string uses = GitHubActionsDefaults.CheckoutAction;
+
+    /// <summary>
+    /// The checkout action to reference. Accepts a complete <c>owner/repo@ref</c> or a bare ref that gets
+    /// appended to <c>actions/checkout</c>. Defaults to the version the generator pins; setting null or
+    /// whitespace restores it.
+    /// </summary>
+    public string Uses
+    {
+        set => uses = GitHubActionsActionReference.Resolve(GitHubActionsDefaults.CheckoutAction, value);
+        get => uses;
+    }
+
     public GitHubActionsSubmodules? Submodules { get; set; }
     public bool? Lfs { get; set; }
     public uint? FetchDepth { get; set; }
@@ -28,7 +41,7 @@ public class GitHubActionsCheckoutStep : GitHubActionsStep
 
     public override void Write(CustomFileWriter writer)
     {
-        writer.WriteLine("- uses: actions/checkout@v7");
+        writer.WriteLine($"- uses: {Uses}");
 
         if (Submodules.HasValue || Lfs.HasValue || FetchDepth.HasValue || Progress.HasValue ||
             !Filter.IsNullOrWhiteSpace() || !Ref.IsNullOrWhiteSpace() || CheckoutWith.Length > 0)

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

@@ -6,6 +6,20 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 
 public class GitHubActionsRunStep : GitHubActionsStep
 {
+    private string setupDotNetAction = GitHubActionsDefaults.SetupDotNetAction;
+
+    /// <summary>
+    /// The SDK-setup action to reference — this step emits the setup, the tool restore, and the build run,
+    /// so only the first of the three is configurable. Accepts a complete <c>owner/repo@ref</c> or a bare
+    /// ref that gets appended to <c>actions/setup-dotnet</c>. Defaults to the version the generator pins;
+    /// setting null or whitespace restores it.
+    /// </summary>
+    public string SetupDotNetAction
+    {
+        set => setupDotNetAction = GitHubActionsActionReference.Resolve(GitHubActionsDefaults.SetupDotNetAction, value);
+        get => setupDotNetAction;
+    }
+
     public string[] InvokedTargets { get; set; }
     public Dictionary<string, string> Imports { get; set; }
 
@@ -14,7 +28,7 @@ public override void Write(CustomFileWriter writer)
         writer.WriteLine("- name: 'Setup: .NET SDK'");
         using (writer.Indent())
         {
-            writer.WriteLine("uses: actions/setup-dotnet@v6");
+            writer.WriteLine($"uses: {SetupDotNetAction}");
             writer.WriteLine("with:");
             using (writer.Indent())
             {