FRD-068: Pipeline Run History Table Widget

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Target Release	v2.0.0 (P2)
T-Shirt Size	M
Type	Widget

---

Document Summary

A DataGrid-based pipeline run history table that lists CI/CD pipeline executions with columns for Run ID, trigger, status, duration, actor, and timestamp. Filterable by status and environment. Complements the existing PipelineStatusCard which shows detail for a single run.

---

Introduction

Overview

SRE and DevOps dashboards need a tabular view of pipeline run history for monitoring, debugging, and auditing. The existing PipelineStatusCard shows a single run’s stages and logs. This widget provides the list-level view, showing many runs at a glance with filtering and sorting.

Goals

• Display pipeline runs in a sortable DataGrid.
• Show Run ID, trigger type, status, duration, actor, and timestamp columns.
• Filter by status (queued, running, success, failed, cancelled) and environment.
• Link to detail view via onSelectRun callback.
• Ship Storybook stories with representative pipeline data.

Non-Goals

• Pipeline execution or triggering.
• Stage-level detail (handled by PipelineStatusCard).
• Log streaming or real-time updates.
• Pipeline configuration or YAML editing.

---

Scope

In Scope

Item	Description
PipelineRunHistoryTable component	DataGrid with pipeline run columns
Status column	Badge with semantic color per PipelineRunStatus
Trigger column	Shows trigger type (push, PR, schedule, manual) with icon
Filters	Toolbar filters for status and environment
Row click	Calls onSelectRun(runId) for drill-down navigation
Storybook stories	Default, Filtered, AllSuccess, MixedStatus, Empty, Loading

Out of Scope

Item	Rationale
Pipeline triggering	Operational action; separate from monitoring
Stage detail	Handled by PipelineStatusCard
Log viewing	Handled by PipelineLogPanel
Real-time updates	Consumer manages via polling or WebSocket

---

Users and Pain Points

User	Pain Point
SRE engineers	No standard table for viewing pipeline run history across environments
DevOps teams	Switching between CI/CD provider UIs and internal dashboards
Release managers	Difficulty auditing who triggered which pipelines and when

---

Definitions

Term	Definition
Pipeline run	A single execution of a CI/CD pipeline
Trigger	The event that initiated the run (push, pull request, schedule, manual)
Environment	The deployment target (dev, staging, production)
Actor	The user or system that triggered the run

---

Current State

pipeline-status-card.tsx shows a single pipeline run with expandable stages, status badges, and a log panel. It uses PipelineRunStatus and PipelineStageStatus types. No table-level view of multiple runs exists. Teams build custom tables for pipeline dashboards.

---

Proposed Solution

Create a PipelineRunHistoryTable widget at src/components/widgets/sre-devops/pipeline-run-history-table.tsx that:

1. Accepts an array of PipelineRun objects.
2. Renders a DataGrid with Run ID, Trigger, Status, Duration, Actor, Environment, and Timestamp columns.
3. Status column reuses the PipelineRunStatus type and badge styling from PipelineStatusCard.
4. Trigger column shows an icon (GitBranch for push, GitPullRequest for PR, Clock for schedule, Play for manual).
5. Toolbar includes status and environment filter dropdowns.
6. Row click calls onSelectRun(runId) for navigation to detail view.

---

Requirements

The table must reuse PipelineRunStatus types from pipeline-status-card.tsx for consistency. It must use TanStack Table for DataGrid rendering.

---

Functional Requirements

ID	Requirement	Priority
FR-01	Render columns: Run ID, Trigger, Status, Duration, Actor, Environment, Timestamp	Must
FR-02	Status column uses Badge with semantic color matching PipelineStatusCard	Must
FR-03	Trigger column shows icon and label for push, PR, schedule, manual	Must
FR-04	Duration column formats milliseconds as human-readable (e.g., “2m 34s”)	Must
FR-05	Timestamp column shows relative time (e.g., “5 min ago”) with full date on hover	Should
FR-06	Toolbar filter for status (multi-select)	Must
FR-07	Toolbar filter for environment (multi-select)	Must
FR-08	Clicking a row calls onSelectRun(runId)	Must
FR-09	Support sorting by Timestamp and Duration	Should
FR-10	Show empty state when no runs match filters	Must
FR-11	Support a loading prop that renders skeleton rows	Should

---

Non-Functional Requirements

ID	Requirement
NFR-01	Renders 500 rows without perceptible lag
NFR-02	Full light/dark theme support
NFR-03	Horizontally scrollable on narrow viewports

---

API / Interface Requirements

import type { PipelineRunStatus } from "@/components/widgets/sre-devops/pipeline-status-card";

type PipelineTrigger = "push" | "pull_request" | "schedule" | "manual";

interface PipelineRun {
  id: string;
  runNumber?: number;
  trigger: PipelineTrigger;
  status: PipelineRunStatus;
  durationMs?: number;
  actor: string;
  actorAvatarUrl?: string;
  environment?: string;
  branch?: string;
  commitSha?: string;
  timestamp: string;           // ISO 8601
}

interface PipelineRunHistoryTableProps {
  runs: PipelineRun[];
  loading?: boolean;
  emptyMessage?: string;
  environments?: string[];     // available environment filter options
  onSelectRun?: (runId: string) => void;
  className?: string;
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	Table uses proper <table> semantics with <th scope="col">
A11Y-02	Status badges include accessible labels
A11Y-03	Trigger icons have aria-label describing the trigger type
A11Y-04	Rows are keyboard-selectable (Enter/Space to activate onSelectRun)
A11Y-05	Filter controls are labeled and keyboard-navigable
A11Y-06	Relative timestamps include full date in title attribute

---

Content and Documentation Requirements

• Storybook doc page explaining relationship to PipelineStatusCard.
• Stories: Default, FilteredByStatus, FilteredByEnv, AllSuccess, MixedStatus, Empty, Loading.
• JSDoc on all exported types.

---

Dependencies

Dependency	Type	Notes
@tanstack/react-table	External	DataGrid core
PipelineRunStatus	Internal	Reuse from pipeline-status-card.tsx
Badge	Internal	Status column
Button	Internal	Filter controls
DropdownMenu	Internal	Status/environment filters
Icon pack	Internal	Trigger type icons

---

Risks and Tradeoffs

Risk	Impact	Mitigation
PipelineRunStatus type coupling	Breaking changes in pipeline-status-card affect this widget	Export types from a shared types file
Large run history	Performance with thousands of rows	Paginate or virtualize; document recommendation
Environment list varies per org	Filter options may be stale	Accept environments prop dynamically

---

Open Questions

1. Should the table support inline expansion to show stage details without navigating away?
2. Do we need a “Re-run” action column for failed pipelines?
3. Should Run ID link to an external CI/CD provider URL?

---

Acceptance Criteria

• Table renders with all specified columns.
• Status badges match PipelineStatusCard styling.
• Trigger icons display correctly for all trigger types.
• Duration formats as human-readable string.
• Status and environment filters work correctly.
• Row click calls onSelectRun with the run ID.
• Empty and loading states render appropriately.
• All Storybook stories render without errors.
• Passes axe accessibility audit with zero violations.
• Unit tests cover rendering, filtering, sorting, and row selection.

---

LLM Handoff Instructions

When implementing this FRD:

1. Create src/components/widgets/sre-devops/pipeline-run-history-table.tsx.
2. Import PipelineRunStatus from ./pipeline-status-card for type reuse.
3. Use @tanstack/react-table with sorting and filtering models.
4. Reference billing-history-table.tsx for DataGrid patterns.
5. Create src/components/widgets/sre-devops/pipeline-run-history-table.stories.tsx.
6. Create src/components/widgets/sre-devops/pipeline-run-history-table.test.tsx.
7. Duration formatting: durationMs to “Xm Ys” format using a utility function.
8. Reuse status badge variant mapping from pipeline-status-card.tsx.

---

Decision Log

Date	Decision	Rationale
2026-05-26	Reuse PipelineRunStatus from existing card	Type consistency across pipeline widgets
2026-05-26	Place in sre-devops/ directory	Follows existing organizational pattern

---

Document History

Date	Version	Author	Changes
2026-05-26	0.1	David Holmes	Initial draft