ci-time-tracker 0.2.0__tar.gz → 0.3.1__tar.gz

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ci-time-tracker
-Version: 0.2.0
+Version: 0.3.1
 Summary: Find where CI time and money go: cost, flaky steps and regressions from GitHub Actions, and a PR comment action
 Author: ci-time-tracker contributors
 License-Expression: MIT
@@ -32,29 +32,58 @@ Dynamic: license-file
 # ci-time-tracker
 
 [![CI](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ci-time-tracker)](https://pypi.org/project/ci-time-tracker/)
 
 Find where your CI time and money go. ci-time-tracker reads your GitHub Actions
 history and reports the steps that cost the most, the ones that are flaky, and
-the ones that got slower, with the commit where it started. Its GitHub Action
-comments on each pull request with how it changes CI time and cost.
+the ones that got slower, with the commit where it started. It also recommends
+changes to your workflows, backed by what your runs actually did. Its GitHub
+Action comments on each pull request with how it changes CI time and cost.
+
+```bash
+pip install ci-time-tracker
+ci-time-tracker --github owner/repo --last 300 --format html --output report.html
+```
+
+[![Report for microsoft/TypeScript](docs/example-report.png)](https://0xwhisp.github.io/ci-time-tracker/example-report.html)
+
+**[See the full example report](https://0xwhisp.github.io/ci-time-tracker/example-report.html)**
+for the last 300 runs of microsoft/TypeScript: three flaky steps, and
+recommendations with up to 135 hours of runner time at stake, such as running
+the Windows legs of three jobs only after merging, since in 87 builds they
+never failed when Linux passed.
+
+Set `GITHUB_TOKEN` first (with the GitHub CLI: `export GITHUB_TOKEN=$(gh auth token)`):
+each run costs a request, and without a token GitHub allows 60 an hour.
 
 ## Features
 
-- **Config Analysis**: Parse GitHub Actions, GitLab CI, and CircleCI configurations to extract pipeline structure
-- **Log Analysis**: Parse build logs to compute actual step durations and statistics
+- **History from the API**: Reads workflow runs, jobs and steps straight from
+  the GitHub Actions API, cached locally so later runs take seconds
 - **Flaky Detection**: Flag steps that both failed and passed on the same commit,
   including runs that only passed on a re-run
-- **Regression Detection**: Flag steps whose duration jumped and stayed up, and
-  name the commit where it started
-- **Cost and Time**: Rank steps by the time they consume, estimate cost per runner,
-  and separate queue time from execution time
+- **Regression Detection**: Flag steps whose duration jumped and stayed up, well
+  beyond their usual variation, and name the commit where it started
+- **Recommendations**: Dependency caching, cancelling superseded pull request
+  runs, and matrix legs that never catch anything, each with the time at stake
+- **Cost and Time**: Rank steps by the time they consume, estimate cost per runner
+  at GitHub's list prices, and separate queue time from execution time
 - **Pull Request Comments**: A GitHub Action that tells each pull request how it
   changes CI time and cost, and whether its failures are in known flaky steps
-- **Multiple Output Formats**: Human-readable text or JSON for dashboard integration
+- **Output Formats**: A self-contained HTML report, Markdown for
+  `$GITHUB_STEP_SUMMARY`, text, or JSON for dashboards; `--fail-on` gates
+- **Config and Log Analysis**: Also parses GitHub Actions, GitLab CI and
+  CircleCI configurations and build logs, for providers without API support yet
 
 ## Installation
 
-Requires Python 3.10+. Not yet published on PyPI; install from source:
+Requires Python 3.10+.
+
+```bash
+pip install ci-time-tracker
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/0xWhisp/ci-time-tracker.git
@@ -296,7 +325,7 @@ consumers, and the full step table collapsed.
 ```yaml
 - name: CI time report
   run: |
-    pip install git+https://github.com/0xWhisp/ci-time-tracker.git
+    pip install ci-time-tracker
     ci-time-tracker --github ${{ github.repository }} --workflow ci.yml       --last 100 --group-matrix --format markdown >> "$GITHUB_STEP_SUMMARY"
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -369,7 +398,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: 0xWhisp/ci-time-tracker@main   # pin a release tag once published
+      - uses: 0xWhisp/ci-time-tracker@v0.3.1
 ```
 
 `workflow_run` runs the copy of the workflow on the default branch with the
@@ -395,6 +424,31 @@ ci-time-tracker --github acme/web --run-id 39102310449 --group-matrix
 ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 ```
 
+### HTML report
+
+`--format html` writes a single self-contained page: summary cards, build
+duration over time for each of the busiest workflows (failures marked, a
+rolling median, outliers kept from flattening the chart), issues with their
+evidence, recommendations, and where the time goes. It has no scripts and loads
+nothing from elsewhere, so it opens offline and can be attached to an issue or
+kept as a CI artifact. It follows the viewer's light or dark mode.
+
+```bash
+ci-time-tracker --github acme/web --group-matrix --format html --output ci-report.html
+```
+
+```yaml
+- run: ci-time-tracker --github ${{ github.repository }} --format html --output ci-report.html
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- uses: actions/upload-artifact@v4
+  with:
+    name: ci-report
+    path: ci-report.html
+```
+
+The JSON output carries the same per-build data under `timeline`.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -405,13 +459,47 @@ ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 | 3 | GitHub API error (rate limit, permissions, not found) |
 | 4 | A quality gate failed |
 
+## Recommendations
+
+With `--github`, ci-time-tracker also reads the workflow files behind the runs
+and suggests changes where the configuration shows a cause and the history
+shows it matters. Neither is enough alone: a slow install step may already be
+cached, and a job without a cache may install in two seconds.
+
+| Recommendation | When |
+|---|---|
+| **Cache dependencies** | A job installs dependencies (pip, uv, poetry, npm, pnpm, yarn, bundler, composer, go) without any cache, and the install takes a median of 20s or more |
+| **Cancel superseded pull request runs** | Pull request runs kept running after a newer push to the same branch started another run, and the workflow has no `concurrency` with `cancel-in-progress` |
+| **Run expensive matrix legs less often** | Over at least 10 builds, the Windows or macOS legs of a job never failed when its Linux legs passed |
+
+Each one comes with its evidence, a concrete change, and what is at stake: the
+time (and cost) the affected steps or jobs used over the analyzed runs. That is
+an upper bound on the saving, not a promise of it. Findings with less than
+10 minutes at stake are left out, so the list stays worth reading.
+
+For example, on pytest-dev/pytest:
+
+```
+RECOMMENDATIONS
+  1. Run the Windows legs of `build` less often (.github/workflows/test.yml)
+     In 79 builds, the Windows legs never failed when the Linux legs passed. They used 68h 08m, 40% of the job's compute.
+     Suggestion: Run the Windows legs only on pushes to the default branch or on a schedule, and keep Linux on pull requests. A platform-specific failure then shows up after merging rather than before.
+     At stake: 68h 08m
+```
+
+Whether a job could start earlier (a `needs` that only orders jobs) is not
+suggested: the configuration cannot tell an ordering from a real dependency on
+the other job's results.
+
 ## Cost Estimates
 
 Costs are estimated from the runner each job ran on, using GitHub's
 [list prices](https://docs.github.com/en/billing/reference/actions-runner-pricing)
 for **private repositories** as of October 2026, with each job rounded up to a
 whole minute. Public repositories pay nothing for standard GitHub-hosted
-runners; larger runners are billed for public repositories too.
+runners; larger runners are billed for public repositories too. When the
+analyzed repository is public (the runs say so), standard runners are priced
+at `$0`, so the estimate counts only what is actually billed.
 
 | Runner | USD per minute |
 |---|---:|
@@ -492,7 +580,11 @@ A step has **regressed** when its duration jumped and stayed up:
 2. The later segment's median must be at least **25%** higher
    (`--regression-threshold`) and at least **10 seconds** higher, so `1s -> 2s`
    steps are not reported.
-3. The most recent 5 builds must still be that slow, so a spike that already
+3. The jump must be at least **three times** the step's usual variation (the
+   median absolute deviation of the noisier segment). With hundreds of steps
+   checked, the best split of a merely noisy one would otherwise clear the
+   thresholds above by chance.
+4. The most recent 5 builds must still be that slow, so a spike that already
    recovered is not reported.
 
 The report names the commit and build where the regression started. A step
@@ -500,6 +592,15 @@ needs at least **10 builds** to be judged; `regression_checked_steps` says how
 many had enough history. With `--group-matrix`, the legs of a build are
 combined into one sample (their median).
 
+Runs that never executed (awaiting a maintainer's approval, skipped by the
+workflow's conditions, or stale) have no timings and are left out; they do not
+count towards `--last`.
+
+When the analyzed runs span several branches, regressions are looked for on
+the repository's default branch only (`regression_branch`). Pull request
+branches run different code with different caches; mixed into one history
+they look like changes that never happened.
+
 ## Supported CI Providers
 
 | Provider | Config Format | Log Format |
@@ -550,7 +651,7 @@ Then, for each release:
 1. Bump `version` in `pyproject.toml` and `__version__` in
    `ci_time_tracker/__init__.py` (a test checks they agree), and add the
    release to [CHANGELOG.md](CHANGELOG.md).
-2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+2. Tag and push: `git tag v0.3.1 && git push origin v0.3.1`.
 3. Create the GitHub release from the tag, with the changelog entry as its
    notes, and tick "Publish this Action to the GitHub Marketplace".
 

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.1}/README.md

@@ -1,29 +1,58 @@
 # ci-time-tracker
 
 [![CI](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/0xWhisp/ci-time-tracker/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ci-time-tracker)](https://pypi.org/project/ci-time-tracker/)
 
 Find where your CI time and money go. ci-time-tracker reads your GitHub Actions
 history and reports the steps that cost the most, the ones that are flaky, and
-the ones that got slower, with the commit where it started. Its GitHub Action
-comments on each pull request with how it changes CI time and cost.
+the ones that got slower, with the commit where it started. It also recommends
+changes to your workflows, backed by what your runs actually did. Its GitHub
+Action comments on each pull request with how it changes CI time and cost.
+
+```bash
+pip install ci-time-tracker
+ci-time-tracker --github owner/repo --last 300 --format html --output report.html
+```
+
+[![Report for microsoft/TypeScript](docs/example-report.png)](https://0xwhisp.github.io/ci-time-tracker/example-report.html)
+
+**[See the full example report](https://0xwhisp.github.io/ci-time-tracker/example-report.html)**
+for the last 300 runs of microsoft/TypeScript: three flaky steps, and
+recommendations with up to 135 hours of runner time at stake, such as running
+the Windows legs of three jobs only after merging, since in 87 builds they
+never failed when Linux passed.
+
+Set `GITHUB_TOKEN` first (with the GitHub CLI: `export GITHUB_TOKEN=$(gh auth token)`):
+each run costs a request, and without a token GitHub allows 60 an hour.
 
 ## Features
 
-- **Config Analysis**: Parse GitHub Actions, GitLab CI, and CircleCI configurations to extract pipeline structure
-- **Log Analysis**: Parse build logs to compute actual step durations and statistics
+- **History from the API**: Reads workflow runs, jobs and steps straight from
+  the GitHub Actions API, cached locally so later runs take seconds
 - **Flaky Detection**: Flag steps that both failed and passed on the same commit,
   including runs that only passed on a re-run
-- **Regression Detection**: Flag steps whose duration jumped and stayed up, and
-  name the commit where it started
-- **Cost and Time**: Rank steps by the time they consume, estimate cost per runner,
-  and separate queue time from execution time
+- **Regression Detection**: Flag steps whose duration jumped and stayed up, well
+  beyond their usual variation, and name the commit where it started
+- **Recommendations**: Dependency caching, cancelling superseded pull request
+  runs, and matrix legs that never catch anything, each with the time at stake
+- **Cost and Time**: Rank steps by the time they consume, estimate cost per runner
+  at GitHub's list prices, and separate queue time from execution time
 - **Pull Request Comments**: A GitHub Action that tells each pull request how it
   changes CI time and cost, and whether its failures are in known flaky steps
-- **Multiple Output Formats**: Human-readable text or JSON for dashboard integration
+- **Output Formats**: A self-contained HTML report, Markdown for
+  `$GITHUB_STEP_SUMMARY`, text, or JSON for dashboards; `--fail-on` gates
+- **Config and Log Analysis**: Also parses GitHub Actions, GitLab CI and
+  CircleCI configurations and build logs, for providers without API support yet
 
 ## Installation
 
-Requires Python 3.10+. Not yet published on PyPI; install from source:
+Requires Python 3.10+.
+
+```bash
+pip install ci-time-tracker
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/0xWhisp/ci-time-tracker.git
@@ -265,7 +294,7 @@ consumers, and the full step table collapsed.
 ```yaml
 - name: CI time report
   run: |
-    pip install git+https://github.com/0xWhisp/ci-time-tracker.git
+    pip install ci-time-tracker
     ci-time-tracker --github ${{ github.repository }} --workflow ci.yml       --last 100 --group-matrix --format markdown >> "$GITHUB_STEP_SUMMARY"
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -338,7 +367,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: 0xWhisp/ci-time-tracker@main   # pin a release tag once published
+      - uses: 0xWhisp/ci-time-tracker@v0.3.1
 ```
 
 `workflow_run` runs the copy of the workflow on the default branch with the
@@ -364,6 +393,31 @@ ci-time-tracker --github acme/web --run-id 39102310449 --group-matrix
 ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 ```
 
+### HTML report
+
+`--format html` writes a single self-contained page: summary cards, build
+duration over time for each of the busiest workflows (failures marked, a
+rolling median, outliers kept from flattening the chart), issues with their
+evidence, recommendations, and where the time goes. It has no scripts and loads
+nothing from elsewhere, so it opens offline and can be attached to an issue or
+kept as a CI artifact. It follows the viewer's light or dark mode.
+
+```bash
+ci-time-tracker --github acme/web --group-matrix --format html --output ci-report.html
+```
+
+```yaml
+- run: ci-time-tracker --github ${{ github.repository }} --format html --output ci-report.html
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- uses: actions/upload-artifact@v4
+  with:
+    name: ci-report
+    path: ci-report.html
+```
+
+The JSON output carries the same per-build data under `timeline`.
+
 ### Exit codes
 
 | Code | Meaning |
@@ -374,13 +428,47 @@ ci-time-tracker --github acme/web --run-id 39102310449 --comment   # post it
 | 3 | GitHub API error (rate limit, permissions, not found) |
 | 4 | A quality gate failed |
 
+## Recommendations
+
+With `--github`, ci-time-tracker also reads the workflow files behind the runs
+and suggests changes where the configuration shows a cause and the history
+shows it matters. Neither is enough alone: a slow install step may already be
+cached, and a job without a cache may install in two seconds.
+
+| Recommendation | When |
+|---|---|
+| **Cache dependencies** | A job installs dependencies (pip, uv, poetry, npm, pnpm, yarn, bundler, composer, go) without any cache, and the install takes a median of 20s or more |
+| **Cancel superseded pull request runs** | Pull request runs kept running after a newer push to the same branch started another run, and the workflow has no `concurrency` with `cancel-in-progress` |
+| **Run expensive matrix legs less often** | Over at least 10 builds, the Windows or macOS legs of a job never failed when its Linux legs passed |
+
+Each one comes with its evidence, a concrete change, and what is at stake: the
+time (and cost) the affected steps or jobs used over the analyzed runs. That is
+an upper bound on the saving, not a promise of it. Findings with less than
+10 minutes at stake are left out, so the list stays worth reading.
+
+For example, on pytest-dev/pytest:
+
+```
+RECOMMENDATIONS
+  1. Run the Windows legs of `build` less often (.github/workflows/test.yml)
+     In 79 builds, the Windows legs never failed when the Linux legs passed. They used 68h 08m, 40% of the job's compute.
+     Suggestion: Run the Windows legs only on pushes to the default branch or on a schedule, and keep Linux on pull requests. A platform-specific failure then shows up after merging rather than before.
+     At stake: 68h 08m
+```
+
+Whether a job could start earlier (a `needs` that only orders jobs) is not
+suggested: the configuration cannot tell an ordering from a real dependency on
+the other job's results.
+
 ## Cost Estimates
 
 Costs are estimated from the runner each job ran on, using GitHub's
 [list prices](https://docs.github.com/en/billing/reference/actions-runner-pricing)
 for **private repositories** as of October 2026, with each job rounded up to a
 whole minute. Public repositories pay nothing for standard GitHub-hosted
-runners; larger runners are billed for public repositories too.
+runners; larger runners are billed for public repositories too. When the
+analyzed repository is public (the runs say so), standard runners are priced
+at `$0`, so the estimate counts only what is actually billed.
 
 | Runner | USD per minute |
 |---|---:|
@@ -461,7 +549,11 @@ A step has **regressed** when its duration jumped and stayed up:
 2. The later segment's median must be at least **25%** higher
    (`--regression-threshold`) and at least **10 seconds** higher, so `1s -> 2s`
    steps are not reported.
-3. The most recent 5 builds must still be that slow, so a spike that already
+3. The jump must be at least **three times** the step's usual variation (the
+   median absolute deviation of the noisier segment). With hundreds of steps
+   checked, the best split of a merely noisy one would otherwise clear the
+   thresholds above by chance.
+4. The most recent 5 builds must still be that slow, so a spike that already
    recovered is not reported.
 
 The report names the commit and build where the regression started. A step
@@ -469,6 +561,15 @@ needs at least **10 builds** to be judged; `regression_checked_steps` says how
 many had enough history. With `--group-matrix`, the legs of a build are
 combined into one sample (their median).
 
+Runs that never executed (awaiting a maintainer's approval, skipped by the
+workflow's conditions, or stale) have no timings and are left out; they do not
+count towards `--last`.
+
+When the analyzed runs span several branches, regressions are looked for on
+the repository's default branch only (`regression_branch`). Pull request
+branches run different code with different caches; mixed into one history
+they look like changes that never happened.
+
 ## Supported CI Providers
 
 | Provider | Config Format | Log Format |
@@ -519,7 +620,7 @@ Then, for each release:
 1. Bump `version` in `pyproject.toml` and `__version__` in
    `ci_time_tracker/__init__.py` (a test checks they agree), and add the
    release to [CHANGELOG.md](CHANGELOG.md).
-2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+2. Tag and push: `git tag v0.3.1 && git push origin v0.3.1`.
 3. Create the GitHub release from the tag, with the changelog entry as its
    notes, and tick "Publish this Action to the GitHub Marketplace".
 

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.1}/ci_time_tracker/__init__.py

@@ -1,3 +1,3 @@
 """ci-time-tracker: A CLI tool for analyzing CI/CD pipeline configurations and build logs."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.1}/ci_time_tracker/analyzer.py

@@ -172,6 +172,7 @@ def analyze_logs(
     group_matrix: bool = False,
     regression_threshold: float = DEFAULT_REGRESSION_THRESHOLD,
     min_samples: int = DEFAULT_MIN_SAMPLES,
+    regression_branch: str | None = None,
 ) -> AnalysisResult:
     """Analyze multiple build logs and compute statistics.
 
@@ -190,6 +191,9 @@ def analyze_logs(
         regression_threshold: Minimum relative duration increase to report,
             e.g. 0.25 for +25%
         min_samples: Minimum builds on each side of a regression
+        regression_branch: When builds span several branches, the one
+            regressions are looked for on (the default branch); defaults to
+            the branch with the most builds
 
     Returns:
         AnalysisResult in log mode with step statistics and detected issues
@@ -297,6 +301,17 @@ def analyze_logs(
             name: {"method": "failure-rate"} for name in detect_flaky_steps(step_stats)
         }
 
+    # Regressions are looked for on one branch only. Pull request branches
+    # run different code with different caches, and mixed into one series
+    # they read as changes that never happened (seen on rubocop, whose
+    # 26 master builds were mixed with 74 from pull requests).
+    branches = Counter(log.metadata.get("branch") for log in logs if log.metadata.get("branch"))
+    if len(branches) > 1:
+        if regression_branch not in branches:
+            regression_branch = branches.most_common(1)[0][0]
+    else:
+        regression_branch = None  # one branch or none known: all builds compare
+
     # Regressions, from one sample per build (the median across matrix legs
     # when they are grouped), in chronological order
     regression_checked = 0
@@ -306,6 +321,7 @@ def analyze_logs(
         samples = [
             (median(values), logs[build_index])
             for build_index, values in sorted(build_durations.items())
+            if regression_branch is None or logs[build_index].metadata.get("branch") == regression_branch
         ]
 
         if len(samples) >= 2 * min_samples:
@@ -344,18 +360,42 @@ def analyze_logs(
     metadata["flaky_detection"] = flaky_method
     metadata["regression_checked_steps"] = regression_checked
     metadata["regression_min_builds"] = 2 * min_samples
+    if regression_branch:
+        metadata["regression_branch"] = regression_branch
     metadata.update(aggregate_job_metrics(logs, pricing))
 
     return AnalysisResult(
         mode="log",
         steps=step_stats,
         total_estimated_duration=None,
+        timeline=build_timeline(logs),
         regressed_steps=[stats.name for stats in step_stats if stats.is_regression],
         flaky_steps=[stats.name for stats in step_stats if stats.is_flaky],
         metadata=metadata,
     )
 
 
+def build_timeline(logs: list[BuildLog]) -> list[dict[str, Any]]:
+    """One entry per build, in the given order, for trend charts.
+
+    Earlier attempts of re-runs are left out: they are part of the same build.
+    """
+    return [
+        {
+            "build_id": log.build_id,
+            "timestamp": log.timestamp.isoformat() if log.timestamp else None,
+            "duration": log.total_duration,
+            "conclusion": log.conclusion,
+            "head_sha": log.head_sha[:7] if log.head_sha else None,
+            "workflow": log.metadata.get("workflow_name"),
+            "branch": log.metadata.get("branch"),
+            "url": log.metadata.get("url"),
+        }
+        for log in logs
+        if not log.metadata.get("superseded_attempt")
+    ]
+
+
 def aggregate_job_metrics(
     logs: list[BuildLog],
     pricing: PricingTable | None = None,

{ci_time_tracker-0.2.0 → ci_time_tracker-0.3.1}/ci_time_tracker/cache.py

@@ -2,7 +2,8 @@
 
 Listing workflow runs is cheap, but every run costs an extra request for its
 jobs. Those payloads no longer change once a run has completed, so they are
-stored in a small SQLite database between invocations.
+stored in a small SQLite database between invocations. Workflow files are
+stored too, keyed by the commit they were read at, which pins their content.
 """
 
 import json
@@ -21,6 +22,14 @@ CREATE TABLE IF NOT EXISTS run_jobs (
     payload TEXT NOT NULL,
     PRIMARY KEY (repo, run_id, run_attempt)
 );
+CREATE TABLE IF NOT EXISTS workflow_files (
+    repo TEXT NOT NULL,
+    path TEXT NOT NULL,
+    ref TEXT NOT NULL,
+    fetched_at TEXT NOT NULL,
+    content TEXT NOT NULL,
+    PRIMARY KEY (repo, path, ref)
+);
 """
 
 
@@ -93,6 +102,23 @@ class RunCache:
         )
         self._connection.commit()
 
+    def get_workflow_file(self, repo: str, path: str, ref: str) -> str | None:
+        """Return a workflow file as read at commit `ref`, or None when not cached."""
+        row = self._connection.execute(
+            "SELECT content FROM workflow_files WHERE repo = ? AND path = ? AND ref = ?",
+            (repo, path, ref),
+        ).fetchone()
+        return None if row is None else row[0]
+
+    def store_workflow_file(self, repo: str, path: str, ref: str, content: str) -> None:
+        """Cache a workflow file as read at commit `ref`."""
+        self._connection.execute(
+            "INSERT OR REPLACE INTO workflow_files "
+            "(repo, path, ref, fetched_at, content) VALUES (?, ?, ?, ?, ?)",
+            (repo, path, ref, datetime.now(timezone.utc).isoformat(), content),
+        )
+        self._connection.commit()
+
     def count(self, repo: str | None = None) -> int:
         """Number of cached runs, optionally limited to one repository."""
         if repo is None: