From 3b621c9fed9a6bee5305a8f2844a9b3aaebf6293 Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Mon, 23 Mar 2026 12:47:25 -0600
Subject: [PATCH] feat: introduce `CIUtils.runTitle()` method

The method will do its best to extract a run name from the CI
environment.
---
 README.md             |  3 ++-
 src/ciUtils.ts        | 29 +++++++++++++++++++++++++++++
 tests/ciutils.spec.ts | 11 ++++++++---
 3 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0df9f1b..952510b 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@ const env = ReportUtils.createEnvironment({ name: 'CI' });
 const report: FlakinessReport.Report = {
   category: 'testreport',
   commitId: worktree.headCommitId(),
+  title: CIUtils.runTitle(),
   url: CIUtils.runUrl(),
   environments: [env],
   suites: [{
@@ -82,7 +83,7 @@ Use this entry point when you need to process or manipulate reports in browser-b
 ## Top-Level Exports
 
 ### Building Reports
-- **`CIUtils`** - Utilities to extract CI/CD information (run URLs, environment detection)
+- **`CIUtils`** - Utilities to extract CI/CD information (run URLs, run titles, environment detection)
 - **`GithubOIDC`** - GitHub Actions OIDC integration for passwordless Flakiness.io authentication
 - **`GitWorktree`** - Git repository utilities for path conversion and commit information
 - **`ReportUtils`** - Namespace with utilities for report creation and manipulation:
diff --git a/src/ciUtils.ts b/src/ciUtils.ts
index dcd9a85..6aa2c97 100644
--- a/src/ciUtils.ts
+++ b/src/ciUtils.ts
@@ -5,6 +5,30 @@
  * from various CI/CD environments, including GitHub Actions, Azure DevOps, Jenkins, and others.
  */
 export namespace CIUtils {
+  /**
+   * Automatically extracts a human-readable CI run title when available.
+   *
+   * This function attempts to detect the current CI environment and return a
+   * stable title that identifies the workflow or pipeline generating the report.
+   *
+   * Supported CI providers (checked in order):
+   * - GitHub Actions (via `GITHUB_WORKFLOW`)
+   *
+   * @returns {string | undefined} The CI run title, or `undefined` if no supported
+   *   CI environment exposes a stable human-readable title.
+   *
+   * @example
+   * ```typescript
+   * const report: FlakinessReport.Report = {
+   *   // ... other report properties
+   *   title: CIUtils.runTitle(),
+   * };
+   * ```
+   */
+  export function runTitle(): string | undefined {
+    return githubActionsTitle();
+  }
+
   /**
    * Automatically extracts the run URL for common continuous integration providers.
    *
@@ -33,6 +57,11 @@ export namespace CIUtils {
   }
 }
 
+function githubActionsTitle(): string | undefined {
+  const title = process.env.GITHUB_WORKFLOW?.trim();
+  return title || undefined;
+}
+
 function githubActions(): string | undefined {
   const serverUrl = process.env.GITHUB_SERVER_URL || 'https://github.com';
   const repo = process.env.GITHUB_REPOSITORY;
diff --git a/tests/ciutils.spec.ts b/tests/ciutils.spec.ts
index 3b51567..79654c6 100644
--- a/tests/ciutils.spec.ts
+++ b/tests/ciutils.spec.ts
@@ -3,9 +3,8 @@ import { CIUtils } from '../src/ciUtils.js';
 
 const isGitHubActions = !!process.env.GITHUB_ACTIONS;
 
-test.skip(!isGitHubActions, 'Only runs in GitHub Actions');
-
-test('runUrl() returns a valid GitHub Actions URL', () => {
+test('returns a valid GitHub Actions URL', () => {
+  test.skip(!isGitHubActions, 'Only runs in GitHub Actions');
   const url = CIUtils.runUrl();
   expect(url).toBeTruthy();
   expect(url).toContain('/actions/runs/');
@@ -13,3 +12,9 @@ test('runUrl() returns a valid GitHub Actions URL', () => {
   // Verify it's a parseable URL
   expect(() => new URL(url!)).not.toThrow();
 });
+
+test('returns a valid runTitle', () => {
+  test.skip(!isGitHubActions, 'Only runs in GitHub Actions');
+  const title = CIUtils.runTitle();
+  expect(title).toBeTruthy();
+});