feat: add neutral job conclusion via allow-failure property

Add TaskResult.Neutral (value 6) and ActionResult.Neutral (value 4) to
allow jobs to report a neutral/warning conclusion to the Checks API.

When a job fails and allow-failure is set (via message property or
ACTIONS_ALLOW_FAILURE env var), the runner reports Neutral instead of
Failed. The server maps this to the Checks API "neutral" conclusion,
which renders as a grey dash icon rather than a red X.

Changes:
- TaskResult enum: add Neutral = 6
- ActionResult enum: add Neutral = 4
- TaskResultUtil: add Neutral mapping in ToActionResult()
- AgentJobRequestMessage: add AllowFailure bool property
- JobRunner: override Failed → Neutral in both CompleteJobAsync overloads
- Tests: cover merge behavior, return code translation, and allow-failure
  logic for both message property and env var fallback

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: atkinsonm

src/Runner.Common/ActionResult.cs

@@ -8,6 +8,8 @@ public enum ActionResult
 
         Cancelled = 2,
 
-        Skipped = 3
+        Skipped = 3,
+
+        Neutral = 4
     }
 }

src/Runner.Common/Util/TaskResultUtil.cs

@@ -71,6 +71,8 @@ public static ActionResult ToActionResult(this TaskResult result)
                     return ActionResult.Cancelled;
                 case TaskResult.Skipped:
                     return ActionResult.Skipped;
+                case TaskResult.Neutral:
+                    return ActionResult.Neutral;
                 default:
                     throw new NotSupportedException(result.ToString());
             }

src/Runner.Worker/JobRunner.cs

@@ -339,6 +339,13 @@ private async Task<TaskResult> CompleteJobAsync(IRunServer runServer, IExecution
             jobContext.Debug($"Finishing: {message.JobDisplayName}");
             TaskResult result = jobContext.Complete(taskResult);
 
+            if (result == TaskResult.Failed && ShouldApplyAllowFailure(jobContext, message))
+            {
+                jobContext.Debug("Job failed but allow-failure is set. Reporting as Neutral.");
+                result = TaskResult.Neutral;
+                jobContext.Result = result;
+            }
+
             var jobQueueTelemetry = await ShutdownQueue(throwOnFailure: false);
             // include any job telemetry from the background upload process.
             if (jobQueueTelemetry?.Count > 0)
@@ -413,6 +420,13 @@ private async Task<TaskResult> CompleteJobAsync(IJobServer jobServer, IExecution
             jobContext.Debug($"Finishing: {message.JobDisplayName}");
             TaskResult result = jobContext.Complete(taskResult);
 
+            if (result == TaskResult.Failed && ShouldApplyAllowFailure(jobContext, message))
+            {
+                jobContext.Debug("Job failed but allow-failure is set. Reporting as Neutral.");
+                result = TaskResult.Neutral;
+                jobContext.Result = result;
+            }
+
             if (_runnerSettings.DisableUpdate == true)
             {
                 await WarningOutdatedRunnerAsync(jobContext, message, result);
@@ -495,6 +509,23 @@ private async Task<TaskResult> CompleteJobAsync(IJobServer jobServer, IExecution
             throw new AggregateException(exceptions);
         }
 
+        private bool ShouldApplyAllowFailure(IExecutionContext jobContext, Pipelines.AgentJobRequestMessage message)
+        {
+            if (message.AllowFailure)
+            {
+                return true;
+            }
+
+            var allowFailureEnv = Environment.GetEnvironmentVariable("ACTIONS_ALLOW_FAILURE");
+            if (string.Equals(allowFailureEnv, "true", StringComparison.OrdinalIgnoreCase))
+            {
+                jobContext.Debug("allow-failure detected via ACTIONS_ALLOW_FAILURE environment variable.");
+                return true;
+            }
+
+            return false;
+        }
+
         private static void AddDebuggerConnectionTelemetry(IExecutionContext jobContext, string result)
         {
             jobContext.Global.JobTelemetry.Add(new JobTelemetry

src/Sdk/DTPipelines/Pipelines/AgentJobRequestMessage.cs

@@ -260,6 +260,13 @@ public bool EnableDebugger
             set;
         }
 
+        [DataMember(EmitDefaultValue = false)]
+        public bool AllowFailure
+        {
+            get;
+            set;
+        }
+
         [DataMember(EmitDefaultValue = false)]
         public DebuggerTunnelInfo DebuggerTunnel
         {

src/Sdk/DTWebApi/WebApi/TaskResult.cs

@@ -22,5 +22,8 @@ public enum TaskResult
 
         [EnumMember]
         Abandoned = 5,
+
+        [EnumMember]
+        Neutral = 6,
     }
 }

src/Test/L0/Util/TaskResultUtilL0.cs

@@ -1,4 +1,5 @@
 using GitHub.DistributedTask.WebApi;
+using GitHub.Runner.Common;
 using GitHub.Runner.Common.Util;
 using Xunit;
 
@@ -200,6 +201,50 @@ public void TaskResultsMerge()
                 merged = TaskResultUtil.MergeTaskResults(TaskResult.Skipped, TaskResult.Failed);
                 // Actual
                 Assert.Equal(TaskResult.Skipped, merged);
+
+                //
+                // Neutral is terminal (not overwritten by subsequent results)
+                //
+                // Act.
+                merged = TaskResultUtil.MergeTaskResults(TaskResult.Neutral, TaskResult.Succeeded);
+                // Actual
+                Assert.Equal(TaskResult.Neutral, merged);
+                // Act.
+                merged = TaskResultUtil.MergeTaskResults(TaskResult.Neutral, TaskResult.Failed);
+                // Actual
+                Assert.Equal(TaskResult.Neutral, merged);
+                // Act.
+                merged = TaskResultUtil.MergeTaskResults(null, TaskResult.Neutral);
+                // Actual
+                Assert.Equal(TaskResult.Neutral, merged);
+                // Act.
+                merged = TaskResultUtil.MergeTaskResults(TaskResult.Succeeded, TaskResult.Neutral);
+                // Actual
+                Assert.Equal(TaskResult.Neutral, merged);
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Common")]
+        public void TaskResultNeutralReturnCodeTranslate()
+        {
+            using (TestHostContext hc = new(this))
+            {
+                TaskResult neutral = TaskResultUtil.TranslateFromReturnCode(TaskResultUtil.TranslateToReturnCode(TaskResult.Neutral));
+                Assert.Equal(TaskResult.Neutral, neutral);
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Common")]
+        public void TaskResultNeutralToActionResult()
+        {
+            using (TestHostContext hc = new(this))
+            {
+                ActionResult actionResult = TaskResult.Neutral.ToActionResult();
+                Assert.Equal(ActionResult.Neutral, actionResult);
             }
         }
     }

src/Test/L0/Worker/JobRunnerL0.cs

@@ -175,5 +175,84 @@ public async Task WorksWithRunnerJobRequestMessageType()
                 Assert.Equal(TaskResult.Succeeded, _jobEc.Result);
             }
         }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task AllowFailureConvertsFailedToNeutral()
+        {
+            using (TestHostContext hc = CreateTestContext())
+            {
+                _jobExtension.Setup(x => x.InitializeJob(It.IsAny<IExecutionContext>(), It.IsAny<Pipelines.AgentJobRequestMessage>()))
+                    .Throws(new Exception());
+
+                var message = GetMessage(JobRequestMessageTypes.RunnerJobRequest);
+                message.AllowFailure = true;
+
+                await _jobRunner.RunAsync(message, _tokenSource.Token);
+
+                Assert.Equal(TaskResult.Neutral, _jobEc.Result);
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task AllowFailureDoesNotAffectSucceeded()
+        {
+            using (TestHostContext hc = CreateTestContext())
+            {
+                var message = GetMessage(JobRequestMessageTypes.RunnerJobRequest);
+                message.AllowFailure = true;
+
+                await _jobRunner.RunAsync(message, _tokenSource.Token);
+
+                Assert.Equal(TaskResult.Succeeded, _jobEc.Result);
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task AllowFailureEnvVarConvertsFailedToNeutral()
+        {
+            using (TestHostContext hc = CreateTestContext())
+            {
+                _jobExtension.Setup(x => x.InitializeJob(It.IsAny<IExecutionContext>(), It.IsAny<Pipelines.AgentJobRequestMessage>()))
+                    .Throws(new Exception());
+
+                var message = GetMessage(JobRequestMessageTypes.RunnerJobRequest);
+
+                Environment.SetEnvironmentVariable("ACTIONS_ALLOW_FAILURE", "true");
+                try
+                {
+                    await _jobRunner.RunAsync(message, _tokenSource.Token);
+                    Assert.Equal(TaskResult.Neutral, _jobEc.Result);
+                }
+                finally
+                {
+                    Environment.SetEnvironmentVariable("ACTIONS_ALLOW_FAILURE", null);
+                }
+            }
+        }
+
+        [Fact]
+        [Trait("Level", "L0")]
+        [Trait("Category", "Worker")]
+        public async Task AllowFailureWithPipelineAgentJobRequest()
+        {
+            using (TestHostContext hc = CreateTestContext())
+            {
+                _jobExtension.Setup(x => x.InitializeJob(It.IsAny<IExecutionContext>(), It.IsAny<Pipelines.AgentJobRequestMessage>()))
+                    .Throws(new Exception());
+
+                var message = GetMessage(JobRequestMessageTypes.PipelineAgentJobRequest);
+                message.AllowFailure = true;
+
+                await _jobRunner.RunAsync(message, _tokenSource.Token);
+
+                Assert.Equal(TaskResult.Neutral, _jobEc.Result);
+            }
+        }
     }
 }