feat: introduce CIUtils.runTitle() method

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:

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;

tests/ciutils.spec.ts

@@ -3,13 +3,18 @@ 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/');
   expect(url).toContain(process.env.GITHUB_RUN_ID!);
   // 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();
+});