Support Conditional Steps in Composite Actions (#1438)

* conditional support for composite actions

* Fix Conditional function evaluation

* Push launch.json temporarily

* Revert "Push launch.json temporarily"

* rename context

* Cleanup comments

* fix success/failure functions to run based on pre/main steps

* idea of step_status

* change to use steps context, WIP

* add inputs to possible if condition expressions

* use action_status

* pr cleanup

* Added right stages

* Test on stage in conditional functions

* Fix naming and formatting

* Fix tests

* Add success and failure L0s

* Remove comment

* Remove whitespace

* Undo formatting

* Add L0 for step-if parsing

* Add ADR

Co-authored-by: Thomas Boop <[email protected]>

docs/adrs/1438-conditional-composite.md

@@ -0,0 +1,71 @@
+# ADR 1438: Support Conditionals In Composite Actions
+
+**Date**: 2021-10-13
+
+**Status**: Accepted
+
+## Context
+
+We recently shipped composite actions, which allows you to reuse individual steps inside an action. 
+However, one of the [most requested features](https://github.com/actions/runner/issues/834) has been a way to support the `if` keyword.
+
+### Goals
+- We want to keep consistent with current behavior
+- We want to support conditionals via the `if` keyword
+- Our built in functions like `success` should be implementable without calling them, for example you can do `job.status == success` rather then `success()` currently.
+
+### How does composite currently work?
+
+Currently, we have limited conditional support in composite actions for `pre` and `post` steps. 
+These are based on the `job status`, and support keywords like `always()`, `failed()`, `success()` and `cancelled()`. 
+However, generic or main steps do **not** support conditionals.
+
+By default, in a regular workflow, a step runs on the `success()` condition. Which looks at the **job** **status**, sees if it is successful and runs.
+
+By default, in a composite action, main steps run until a single step fails in that composite action, then the composite action is halted early. It does **not** care about the job status.
+Pre, and post steps in composite actions use the job status to determine if they should run.
+
+### How do we go forward?
+
+Well, if we think about what composite actions are currently doing when invoking main steps, they are checking if the current composite action is successful. 
+Lets formalize that concept into a "real" idea.
+
+- We will add an `action_status` field to the github context to mimic the [job's context status](https://docs.github.com/en/actions/learn-github-actions/contexts#job-context).
+  - We have an existing concept that does this `action_path` which is only set for composite actions on the github context.
+- In a composite action during a main step, the `success()` function will check if `action_status == success`, rather then `job_status == success`. Failure will work the same way. 
+  - Pre and post steps in composite actions will not change, they will continue to check the job status.
+
+
+### Nested Scenario
+For nested composite actions, we will follow the existing behavior, you only care about your current composite action, not any parents. 
+For example, lets imagine a scenario with a simple nested composite action
+
+```
+- Job
+  - Regular Step
+  - Composite Action
+    - runs: exit 1
+    - if: always()
+      uses: A child composite action
+        - if: success()
+          runs: echo "this should print"
+        - runs: echo "this should also print"
+    - if: success()
+      runs: echo "this will not print as the current composite action has failed already"
+      
+```
+The child composite actions steps should run in this example, the child composite action has not yet failed, so it should run all steps until a step fails. This is consistent with how a composite action currently works in production if the main job fails but a composite action is invoked with `if:always()` or `if: failure()`
+
+### Other options explored
+We could add the `current_step_status` to the job context rather then `__status` to the steps context, however this comes with two major downsides:
+- We need to support the field for every type of step, because its non trivial to remove a field from the job context once it has been added (its readonly)
+  - For all actions besides composite it would only every be `success`
+  - Its weird to have a `current_step` value on the job context
+- We also explored a `__status` on the steps context.
+  - The `__` is required to prevent us from colliding with a step with id: status
+  - This felt wrong because the naming was not smooth, and did not fit into current conventions.
+
+### Consequences
+- github context has a new field for the status of the current composite action.
+- We support conditional's in composite actions
+- We keep the existing behavior for all users, but allow them to expand that functionality.

src/Runner.Worker/ActionManager.cs

@@ -1047,7 +1047,6 @@ private ActionSetupInfo PrepareRepositoryActionAsync(IExecutionContext execution
                         }
                     }
 
-                    // TODO: remove once we remove the DistributedTask.EnableCompositeActions FF
                     foreach (var step in compositeAction.Steps)
                     {
                         if (string.IsNullOrEmpty(executionContext.Global.Variables.Get("DistributedTask.EnableCompositeActions")) && step.Reference.Type != Pipelines.ActionSourceType.Script)

src/Runner.Worker/ExecutionContext.cs

@@ -40,6 +40,7 @@ public interface IExecutionContext : IRunnerService
         string ScopeName { get; }
         string SiblingScopeName { get; }
         string ContextName { get; }
+        ActionRunStage Stage { get; }
         Task ForceCompleted { get; }
         TaskResult? Result { get; set; }
         TaskResult? Outcome { get; set; }
@@ -76,8 +77,8 @@ public interface IExecutionContext : IRunnerService
         // Initialize
         void InitializeJob(Pipelines.AgentJobRequestMessage message, CancellationToken token);
         void CancelToken();
-        IExecutionContext CreateChild(Guid recordId, string displayName, string refName, string scopeName, string contextName, Dictionary<string, string> intraActionState = null, int? recordOrder = null, IPagingLogger logger = null, bool isEmbedded = false, CancellationTokenSource cancellationTokenSource = null, Guid embeddedId = default(Guid), string siblingScopeName = null);
-        IExecutionContext CreateEmbeddedChild(string scopeName, string contextName, Guid embeddedId, Dictionary<string, string> intraActionState = null, string siblingScopeName = null);
+        IExecutionContext CreateChild(Guid recordId, string displayName, string refName, string scopeName, string contextName, ActionRunStage stage, Dictionary<string, string> intraActionState = null, int? recordOrder = null, IPagingLogger logger = null, bool isEmbedded = false, CancellationTokenSource cancellationTokenSource = null, Guid embeddedId = default(Guid), string siblingScopeName = null);
+        IExecutionContext CreateEmbeddedChild(string scopeName, string contextName, Guid embeddedId, ActionRunStage stage, Dictionary<string, string> intraActionState = null, string siblingScopeName = null);
 
         // logging
         long Write(string tag, string message);
@@ -144,6 +145,7 @@ public sealed class ExecutionContext : RunnerService, IExecutionContext
         public string ScopeName { get; private set; }
         public string SiblingScopeName { get; private set; }
         public string ContextName { get; private set; }
+        public ActionRunStage Stage { get; private set; }
         public Task ForceCompleted => _forceCompleted.Task;
         public CancellationToken CancellationToken => _cancellationTokenSource.Token;
         public Dictionary<string, string> IntraActionState { get; private set; }
@@ -292,7 +294,7 @@ public void RegisterPostJobStep(IStep step)
             Root.PostJobSteps.Push(step);
         }
 
-        public IExecutionContext CreateChild(Guid recordId, string displayName, string refName, string scopeName, string contextName, Dictionary<string, string> intraActionState = null, int? recordOrder = null, IPagingLogger logger = null, bool isEmbedded = false, CancellationTokenSource cancellationTokenSource = null, Guid embeddedId = default(Guid), string siblingScopeName = null)
+        public IExecutionContext CreateChild(Guid recordId, string displayName, string refName, string scopeName, string contextName, ActionRunStage stage, Dictionary<string, string> intraActionState = null, int? recordOrder = null, IPagingLogger logger = null, bool isEmbedded = false, CancellationTokenSource cancellationTokenSource = null, Guid embeddedId = default(Guid), string siblingScopeName = null)
         {
             Trace.Entering();
 
@@ -301,6 +303,7 @@ public void RegisterPostJobStep(IStep step)
             child.Global = Global;
             child.ScopeName = scopeName;
             child.ContextName = contextName;
+            child.Stage = stage;
             child.EmbeddedId = embeddedId;
             child.SiblingScopeName = siblingScopeName;
             child.JobTelemetry = JobTelemetry;
@@ -351,9 +354,9 @@ public void RegisterPostJobStep(IStep step)
         /// An embedded execution context shares the same record ID, record name, logger,
         /// and a linked cancellation token.
         /// </summary>
-        public IExecutionContext CreateEmbeddedChild(string scopeName, string contextName, Guid embeddedId, Dictionary<string, string> intraActionState = null, string siblingScopeName = null)
+        public IExecutionContext CreateEmbeddedChild(string scopeName, string contextName, Guid embeddedId, ActionRunStage stage, Dictionary<string, string> intraActionState = null, string siblingScopeName = null)
         {
-            return Root.CreateChild(_record.Id, _record.Name, _record.Id.ToString("N"), scopeName, contextName, logger: _logger, isEmbedded: true, cancellationTokenSource: CancellationTokenSource.CreateLinkedTokenSource(_cancellationTokenSource.Token), intraActionState: intraActionState, embeddedId: embeddedId, siblingScopeName: siblingScopeName);
+            return Root.CreateChild(_record.Id, _record.Name, _record.Id.ToString("N"), scopeName, contextName, stage, logger: _logger, isEmbedded: true, cancellationTokenSource: CancellationTokenSource.CreateLinkedTokenSource(_cancellationTokenSource.Token), intraActionState: intraActionState, embeddedId: embeddedId, siblingScopeName: siblingScopeName);
         }
 
         public void Start(string currentOperation = null)
@@ -944,7 +947,7 @@ private IExecutionContext CreatePostChild(string displayName, Dictionary<string,
             }
 
             var newGuid = Guid.NewGuid();
-            return CreateChild(newGuid, displayName, newGuid.ToString("N"), null, null, intraActionState, _childTimelineRecordOrder - Root.PostJobSteps.Count, siblingScopeName: siblingScopeName);
+            return CreateChild(newGuid, displayName, newGuid.ToString("N"), null, null, ActionRunStage.Post, intraActionState, _childTimelineRecordOrder - Root.PostJobSteps.Count, siblingScopeName: siblingScopeName);
         }
     }
 

src/Runner.Worker/Expressions/FailureFunction.cs

@@ -24,8 +24,19 @@ protected sealed override object EvaluateCore(EvaluationContext evaluationContex
             ArgUtil.NotNull(templateContext, nameof(templateContext));
             var executionContext = templateContext.State[nameof(IExecutionContext)] as IExecutionContext;
             ArgUtil.NotNull(executionContext, nameof(executionContext));
-            ActionResult jobStatus = executionContext.JobContext.Status ?? ActionResult.Success;
-            return jobStatus == ActionResult.Failure;
+
+            // Decide based on 'action_status' for composite MAIN steps and 'job.status' for pre, post and job-level steps
+            var isCompositeMainStep = executionContext.IsEmbedded && executionContext.Stage == ActionRunStage.Main;
+            if (isCompositeMainStep)
+            {
+                ActionResult actionStatus = EnumUtil.TryParse<ActionResult>(executionContext.GetGitHubContext("action_status")) ?? ActionResult.Success;
+                return actionStatus == ActionResult.Failure;
+            }
+            else
+            {
+                ActionResult jobStatus = executionContext.JobContext.Status ?? ActionResult.Success;
+                return jobStatus == ActionResult.Failure;
+            }
         }
     }
 }

src/Runner.Worker/Expressions/SuccessFunction.cs

@@ -24,8 +24,19 @@ protected sealed override object EvaluateCore(EvaluationContext evaluationContex
             ArgUtil.NotNull(templateContext, nameof(templateContext));
             var executionContext = templateContext.State[nameof(IExecutionContext)] as IExecutionContext;
             ArgUtil.NotNull(executionContext, nameof(executionContext));
-            ActionResult jobStatus = executionContext.JobContext.Status ?? ActionResult.Success;
-            return jobStatus == ActionResult.Success;
+
+            // Decide based on 'action_status' for composite MAIN steps and 'job.status' for pre, post and job-level steps
+            var isCompositeMainStep = executionContext.IsEmbedded && executionContext.Stage == ActionRunStage.Main;
+            if (isCompositeMainStep)
+            {
+                ActionResult actionStatus = EnumUtil.TryParse<ActionResult>(executionContext.GetGitHubContext("action_status")) ?? ActionResult.Success;
+                return actionStatus == ActionResult.Success;
+            }
+            else
+            {
+                ActionResult jobStatus = executionContext.JobContext.Status ?? ActionResult.Success;
+                return jobStatus == ActionResult.Success;
+            }
         }
     }
 }