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,119 @@
+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 a user-supplied action override into the <c>uses:</c> value to emit. The consumer-facing
+    /// contract — the accepted forms and what each means — is documented on the public properties that feed
+    /// this, <see cref="GitHubActionsAttribute.CheckoutAction"/> and its siblings; this is the
+    /// implementation behind them.
+    /// <para/>
+    /// A trailing <c># comment</c> is split off and set aside before classifying, so it never sways the
+    /// decision. What remains is a complete reference when it contains an <c>@</c> (emitted verbatim),
+    /// otherwise a bare ref appended to <paramref name="defaultAction"/>'s <c>owner/repo</c> — with a
+    /// leading <c>@</c> required to mark a slash-bearing value as a ref rather than an <c>owner/repo</c>.
+    /// Local (<c>./path</c>) and container (<c>docker://</c>) references pass through untouched.
+    /// </summary>
+    /// <param name="defaultAction">The <c>owner/repo@ref</c> the generator pins, used both as the fallback
+    /// and as the action a bare ref is appended to.</param>
+    /// <param name="value">The override to resolve; null or whitespace yields <paramref name="defaultAction"/>.</param>
+    /// <param name="origin">Names what carries <paramref name="value"/> — a property and its workflow — so a
+    /// rejected reference points at the declaration to fix. Prefixed onto every message.</param>
+    /// <exception cref="ArgumentException">Thrown via <see cref="Assert"/> when <paramref name="value"/> is
+    /// not a reference the generator can emit.</exception>
+    public static string Resolve(string defaultAction, string value, string origin)
+    {
+        if (value.IsNullOrWhiteSpace())
+            return defaultAction;
+
+        Assert.True(value.All(x => !char.IsControl(x)),
+            $"{origin}: action reference '{value}' must be a single line without control characters");
+
+        var (reference, comment) = SplitComment(value.Trim());
+
+        Assert.True(!reference.IsNullOrWhiteSpace(),
+            $"{origin}: 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)),
+            $"{origin}: 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 = ResolveMarketplaceReference(defaultAction, reference, origin);
+        }
+
+        return comment == null ? reference : $"{reference} {comment}";
+    }
+
+    /// <summary>
+    /// Resolves a comment-free reference to an action on GitHub — the <c>owner/repo@ref</c> case and the
+    /// bare-ref case — rejecting anything that names no ref or is ambiguous between the two. Local and
+    /// container references never reach here; they carry no ref to resolve.
+    /// </summary>
+    private static string ResolveMarketplaceReference(string defaultAction, string reference, string origin)
+    {
+        // 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('/'),
+                $"{origin}: action reference '{reference}' must name the action as 'owner/repo@ref'");
+            Assert.True(!gitReference.IsNullOrWhiteSpace() && !gitReference.Contains('@'),
+                $"{origin}: action reference '{reference}' must name exactly one version or commit after the '@'");
+
+            return reference;
+        }
+
+        Assert.True(!reference.IsNullOrWhiteSpace() && !reference.Contains('@'),
+            $"{origin}: action reference '{reference}' must name exactly one version or commit");
+        Assert.True(isExplicitBareRef || !reference.Contains('/'),
+            $"{origin}: 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}";
+    }
+
+    /// <summary>
+    /// Takes the <c>owner/repo</c> half of a pinned default, which is what a bare ref gets appended to.
+    /// </summary>
+    private static string GetActionName(string defaultAction)
+    {
+        var separatorIndex = defaultAction.IndexOf('@');
+        return separatorIndex > 0 ? defaultAction.Substring(startIndex: 0, separatorIndex) : defaultAction;
+    }
+
+    /// <summary>
+    /// Splits a trailing YAML comment off the reference, so neither classification nor validation can be
+    /// swayed by a <c>/</c> or <c>@</c> that only appears inside it. A <c>#</c> opens a comment only at the
+    /// start of the scalar or after whitespace; anywhere else it is an ordinary character and stays part of
+    /// the reference.
+    /// </summary>
+    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,26 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 
 public class GitHubActionsArtifactStep : GitHubActionsStep
 {
+    /// <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
+    {
+        get;
+        set => field = GitHubActionsActionReference.Resolve(
+            GitHubActionsDefaults.UploadArtifactAction, value, $"{nameof(GitHubActionsArtifactStep)}.{nameof(Uses)}");
+    } = GitHubActionsDefaults.UploadArtifactAction;
+
     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,18 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 // https://github.com/actions/cache
 public class GitHubActionsCacheStep : GitHubActionsStep
 {
+    /// <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
+    {
+        get;
+        set => field = GitHubActionsActionReference.Resolve(
+            GitHubActionsDefaults.CacheAction, value, $"{nameof(GitHubActionsCacheStep)}.{nameof(Uses)}");
+    } = GitHubActionsDefaults.CacheAction;
+
     public string[] IncludePatterns { get; set; }
     public string[] ExcludePatterns { get; set; }
     public string[] KeyFiles { get; set; }
@@ -17,7 +29,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,18 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 
 public class GitHubActionsCheckoutStep : GitHubActionsStep
 {
+    /// <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
+    {
+        get;
+        set => field = GitHubActionsActionReference.Resolve(
+            GitHubActionsDefaults.CheckoutAction, value, $"{nameof(GitHubActionsCheckoutStep)}.{nameof(Uses)}");
+    } = GitHubActionsDefaults.CheckoutAction;
+
     public GitHubActionsSubmodules? Submodules { get; set; }
     public bool? Lfs { get; set; }
     public uint? FetchDepth { get; set; }
@@ -28,7 +40,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,19 @@ namespace Fallout.Common.CI.GitHubActions.Configuration;
 
 public class GitHubActionsRunStep : GitHubActionsStep
 {
+    /// <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
+    {
+        get;
+        set => field = GitHubActionsActionReference.Resolve(
+            GitHubActionsDefaults.SetupDotNetAction, value, $"{nameof(GitHubActionsRunStep)}.{nameof(SetupDotNetAction)}");
+    } = GitHubActionsDefaults.SetupDotNetAction;
+
     public string[] InvokedTargets { get; set; }
     public Dictionary<string, string> Imports { get; set; }
 
@@ -14,7 +27,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())
             {