(GH-4891) Add missing GitHub Actions environment variables and XML documentation

Expose documented GitHub Actions default environment variables that were
previously unavailable through the Cake provider, and improve API documentation
with integration-inspired XML examples.

- Add workflow properties: ActionRepository, ActorId, RepositoryId, RepositoryOwnerId, RetentionDays, TriggeringActor, WorkflowRef, and WorkflowSha
- Add runner properties: IsDebug and Environment, with new GitHubActionsRunnerEnvironment enum
- Extend GitHubActionsInfoFixture and unit tests for new workflow and runner properties
- Add XML documentation examples to IGitHubActionsProvider, GitHubActionsCommands, GitHubActionsRunnerInfo, GitHubActionsRuntimeInfo, and GitHubActionsPullRequestInfo
- Expand GitHub Actions integration step summary to exercise new environment properties on CI
- fixes #4891

Author: devlead

src/Cake.Common.Tests/Fixtures/Build/GitHubActionsInfoFixture.cs

@@ -33,10 +33,14 @@ public GitHubActionsInfoFixture()
             Environment.GetEnvironmentVariable("ImageOS").Returns("ubuntu20");
             Environment.GetEnvironmentVariable("ImageVersion").Returns("20211209.3");
             Environment.GetEnvironmentVariable("RUNNER_USER").Returns("runner");
+            Environment.GetEnvironmentVariable("RUNNER_DEBUG").Returns("1");
+            Environment.GetEnvironmentVariable("RUNNER_ENVIRONMENT").Returns("github-hosted");
 
             Environment.GetEnvironmentVariable("GITHUB_ACTION").Returns("run1");
             Environment.GetEnvironmentVariable("GITHUB_ACTION_PATH").Returns("/path/to/action");
+            Environment.GetEnvironmentVariable("GITHUB_ACTION_REPOSITORY").Returns("actions/checkout");
             Environment.GetEnvironmentVariable("GITHUB_ACTOR").Returns("dependabot");
+            Environment.GetEnvironmentVariable("GITHUB_ACTOR_ID").Returns("1234567");
             Environment.GetEnvironmentVariable("GITHUB_API_URL").Returns("https://api.github.com");
             Environment.GetEnvironmentVariable("GITHUB_BASE_REF").Returns("master");
             Environment.GetEnvironmentVariable("GITHUB_EVENT_NAME").Returns("pull_request");
@@ -46,12 +50,18 @@ public GitHubActionsInfoFixture()
             Environment.GetEnvironmentVariable("GITHUB_JOB").Returns("job");
             Environment.GetEnvironmentVariable("GITHUB_REF").Returns("refs/pull/1/merge");
             Environment.GetEnvironmentVariable("GITHUB_REPOSITORY").Returns("cake-build/cake");
+            Environment.GetEnvironmentVariable("GITHUB_REPOSITORY_ID").Returns("123456789");
             Environment.GetEnvironmentVariable("GITHUB_REPOSITORY_OWNER").Returns("cake-build");
+            Environment.GetEnvironmentVariable("GITHUB_REPOSITORY_OWNER_ID").Returns("9876543");
+            Environment.GetEnvironmentVariable("GITHUB_RETENTION_DAYS").Returns("90");
             Environment.GetEnvironmentVariable("GITHUB_RUN_ID").Returns("34058136");
             Environment.GetEnvironmentVariable("GITHUB_RUN_NUMBER").Returns("60");
             Environment.GetEnvironmentVariable("GITHUB_SERVER_URL").Returns("https://github.com");
             Environment.GetEnvironmentVariable("GITHUB_SHA").Returns("d1e4f990f57349334368c8253382abc63be02d73");
+            Environment.GetEnvironmentVariable("GITHUB_TRIGGERING_ACTOR").Returns("octocat");
             Environment.GetEnvironmentVariable("GITHUB_WORKFLOW").Returns("Build");
+            Environment.GetEnvironmentVariable("GITHUB_WORKFLOW_REF").Returns("cake-build/cake/.github/workflows/build.yml@refs/heads/main");
+            Environment.GetEnvironmentVariable("GITHUB_WORKFLOW_SHA").Returns("a1b2c3d4e5f6789012345678901234567890abcd");
             Environment.GetEnvironmentVariable("GITHUB_WORKSPACE").Returns("/home/runner/work/cake/cake");
             Environment.GetEnvironmentVariable("GITHUB_RUN_ATTEMPT").Returns("2");
             Environment.GetEnvironmentVariable("GITHUB_REF_PROTECTED").Returns("true");
@@ -70,9 +80,11 @@ public GitHubActionsInfoFixture()
             Environment.Runtime.CakeVersion.Returns(CakeTestVersion);
         }
 
-        public GitHubActionsRunnerInfo CreateRunnerInfo(string architecture = null)
+        public GitHubActionsRunnerInfo CreateRunnerInfo(string architecture = null, string debug = "1", string environment = "github-hosted")
         {
             Environment.GetEnvironmentVariable("RUNNER_ARCH").Returns(architecture);
+            Environment.GetEnvironmentVariable("RUNNER_DEBUG").Returns(debug);
+            Environment.GetEnvironmentVariable("RUNNER_ENVIRONMENT").Returns(environment);
             return new GitHubActionsRunnerInfo(Environment);
         }
 

src/Cake.Common.Tests/Unit/Build/GitHubActions/Data/GitHubActionsRunnerInfoTests.cs

@@ -159,5 +159,43 @@ public void Should_Return_Correct_Value(string value, GitHubActionsArchitecture
                 Assert.Equal(expected, result);
             }
         }
+
+        public sealed class TheIsDebugProperty
+        {
+            [Theory]
+            [InlineData("1", true)]
+            [InlineData("", false)]
+            [InlineData("true", false)]
+            public void Should_Return_Correct_Value(string value, bool expected)
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateRunnerInfo(debug: value);
+
+                // When
+                var result = info.IsDebug;
+
+                // Then
+                Assert.Equal(expected, result);
+            }
+        }
+
+        public sealed class TheEnvironmentProperty
+        {
+            [Theory]
+            [InlineData("github-hosted", GitHubActionsRunnerEnvironment.GitHubHosted)]
+            [InlineData("self-hosted", GitHubActionsRunnerEnvironment.SelfHosted)]
+            [InlineData("", GitHubActionsRunnerEnvironment.Unknown)]
+            public void Should_Return_Correct_Value(string value, GitHubActionsRunnerEnvironment expected)
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateRunnerInfo(environment: value);
+
+                // When
+                var result = info.Environment;
+
+                // Then
+                Assert.Equal(expected, result);
+            }
+        }
     }
 }

src/Cake.Common.Tests/Unit/Build/GitHubActions/Data/GitHubActionsWorkflowInfoTests.cs

@@ -42,6 +42,22 @@ public void Should_Return_Correct_Value()
             }
         }
 
+        public sealed class TheActionRepositoryProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.ActionRepository;
+
+                // Then
+                Assert.Equal("actions/checkout", result);
+            }
+        }
+
         public sealed class TheActorProperty
         {
             [Fact]
@@ -58,6 +74,22 @@ public void Should_Return_Correct_Value()
             }
         }
 
+        public sealed class TheActorIdProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.ActorId;
+
+                // Then
+                Assert.Equal("1234567", result);
+            }
+        }
+
         public sealed class TheApiUrlProperty
         {
             [Fact]
@@ -202,6 +234,22 @@ public void Should_Return_Correct_Value()
             }
         }
 
+        public sealed class TheRepositoryIdProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.RepositoryId;
+
+                // Then
+                Assert.Equal("123456789", result);
+            }
+        }
+
         public sealed class TheRepositoryOwnerProperty
         {
             [Fact]
@@ -218,6 +266,38 @@ public void Should_Return_Correct_Value()
             }
         }
 
+        public sealed class TheRepositoryOwnerIdProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.RepositoryOwnerId;
+
+                // Then
+                Assert.Equal("9876543", result);
+            }
+        }
+
+        public sealed class TheRetentionDaysProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.RetentionDays;
+
+                // Then
+                Assert.Equal(90, result);
+            }
+        }
+
         public sealed class TheRunIdProperty
         {
             [Fact]
@@ -282,6 +362,22 @@ public void Should_Return_Correct_Value()
             }
         }
 
+        public sealed class TheTriggeringActorProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.TriggeringActor;
+
+                // Then
+                Assert.Equal("octocat", result);
+            }
+        }
+
         public sealed class TheWorkflowProperty
         {
             [Fact]
@@ -298,6 +394,38 @@ public void Should_Return_Correct_Value()
             }
         }
 
+        public sealed class TheWorkflowRefProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.WorkflowRef;
+
+                // Then
+                Assert.Equal("cake-build/cake/.github/workflows/build.yml@refs/heads/main", result);
+            }
+        }
+
+        public sealed class TheWorkflowShaProperty
+        {
+            [Fact]
+            public void Should_Return_Correct_Value()
+            {
+                // Given
+                var info = new GitHubActionsInfoFixture().CreateWorkflowInfo();
+
+                // When
+                var result = info.WorkflowSha;
+
+                // Then
+                Assert.Equal("a1b2c3d4e5f6789012345678901234567890abcd", result);
+            }
+        }
+
         public sealed class TheWorkspaceProperty
         {
             [Fact]