From fa757e65107f4deab9f96b051d1ad37098542eee Mon Sep 17 00:00:00 2001
From: Scion <scion@studiowhy.net>
Date: Sun, 21 Dec 2025 16:25:50 -0800
Subject: [PATCH] Added some comments to the download script.

---
 .../download-previous-artifacts.cs                | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/gitea/download-previous-artifacts/download-previous-artifacts.cs b/gitea/download-previous-artifacts/download-previous-artifacts.cs
index ae359f9..8b69b2b 100644
--- a/gitea/download-previous-artifacts/download-previous-artifacts.cs
+++ b/gitea/download-previous-artifacts/download-previous-artifacts.cs
@@ -2,6 +2,9 @@
 
 #:package StudioWhy.Gitea.Net.API@1.25.0.2
 
+// Script to download artifacts from previous Gitea workflow runs
+// Supports filtering by workflow name, branch, and artifact patterns
+
 using System.Net;
 using System.Text;
 using System.Text.RegularExpressions;
@@ -14,6 +17,7 @@ using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 
+// Read configuration from INPUTS environment variable (JSON format)
 string jsonInput = Environment.GetEnvironmentVariable("INPUTS") ?? "{}";
 const string name = "Download Previous Artifacts";
 Console.WriteLine($"::group::{name} - Inputs");
@@ -23,6 +27,7 @@ Console.WriteLine("::endgroup::");
 byte[] jsonBytes = Encoding.UTF8.GetBytes(jsonInput);
 using MemoryStream memoryStream = new(jsonBytes);
 
+// Build configuration from multiple sources: local settings, JSON input, and environment
 string currentDir = Directory.GetCurrentDirectory();
 IConfiguration configuration = new ConfigurationBuilder()
     .SetBasePath(currentDir)
@@ -37,6 +42,7 @@ string password = configuration["password"] ?? string.Empty;
 
 string repoFullName = configuration["repoFullName"] ?? string.Empty;
 
+// Parse repository name into owner and repo components
 string[] repoParts = repoFullName.Split('/');
 if (repoParts.Length != 2)
 {
@@ -45,6 +51,7 @@ if (repoParts.Length != 2)
 string repoOwner = repoParts[0];
 string repoName = repoParts[1];
 
+// Convert wildcard patterns to regex for flexible matching
 string workflowPattern = configuration["workflowPattern"] ?? "*";
 Regex workflowRegex = WildcardToRegex(workflowPattern);
 
@@ -61,7 +68,7 @@ if (!string.IsNullOrEmpty(unzipDir) && !Path.IsPathFullyQualified(unzipDir))
 }
 bool.TryParse(configuration["deleteAfterUnzip"], out bool deleteAfterUnzip);
 
-// Configure services
+// Configure Gitea API client with authentication
 ServiceCollection services = new();
 services.AddApi(o =>
 {
@@ -96,6 +103,7 @@ static Regex WildcardToRegex(string pattern, RegexOptions options = RegexOptions
     return new(regexString, options);
 }
 
+// Fetch successful workflow runs from the repository
 Console.WriteLine($"Retrieving workflow runs for repository: {repoOwner}/{repoName} with pattern: {workflowPattern}");
 IGetWorkflowRunsApiResponse getWorkflowRunsApiResponse = await repositoryApi.GetWorkflowRunsOrDefaultAsync(repoOwner, repoName, status: "success", page: 1, cancellationToken: CancellationToken.None);
 if (!getWorkflowRunsApiResponse.TryOk(out ActionWorkflowRunsResponse workflowRunResponse))
@@ -104,6 +112,7 @@ if (!getWorkflowRunsApiResponse.TryOk(out ActionWorkflowRunsResponse workflowRun
     return 1;
 }
 
+// Check if a workflow run matches both workflow and branch patterns
 bool WorkflowMatchesBranch(ActionWorkflowRun workflowRun)
 {
     string[] pathParts = workflowRun.Path.Split('@');
@@ -126,6 +135,7 @@ if (!artifacts.TryOk(out ActionArtifactsResponse artifactsResponse))
     Console.WriteLine("Failed to retrieve artifacts.");
     return 1;
 }
+// Filter artifacts by name pattern
 ActionArtifact[] artifactsToDownload = artifactsResponse.Artifacts.Where(a => artifactRegex.IsMatch(a.Name)).ToArray();
 if (artifactsToDownload.Length is 0)
 {
@@ -133,6 +143,7 @@ if (artifactsToDownload.Length is 0)
     return 1;
 }
 
+// Prepare output buffers for GitHub Actions multi-line output format
 StringBuilder namesBuilder = new();
 namesBuilder.AppendLine("downloadedArtifactNames<<EOF");
 
@@ -147,6 +158,7 @@ foreach (ActionArtifact artifact in artifactsToDownload)
 {
     Console.WriteLine($"Artifact: {artifact.Name}, URL: {artifact.ArchiveDownloadUrl}");
 
+    // Get signed download URL via redirect
     IDownloadArtifactApiResponse downloadArtifactApiResponse = await repositoryApi.DownloadArtifactAsync(repoOwner, repoName, artifact.Id.ToString(), CancellationToken.None);
     Uri? signedUrl = downloadArtifactApiResponse.Headers.Location;
     if (downloadArtifactApiResponse.StatusCode is not HttpStatusCode.Found || signedUrl is null)
@@ -186,6 +198,7 @@ namesBuilder.AppendLine("EOF");
 artifactsBuilder.AppendLine("EOF");
 artifactsDirsBuilder.AppendLine("EOF");
 
+// Write outputs to GitHub Actions output file or console
 string? githubOutput = configuration["GITHUB_OUTPUT"];
 if (!string.IsNullOrEmpty(githubOutput))
 {