[jdx]

Closes #121 (PR 4 of 4, so this is the one that closes it once the earlier ones are merged: #269, #272, #274). It is independent of the others, except that all four edit docs/usage.md, man/jactionlint.1.ronn and command_options.go, so expect trivial merge conflicts there.

This is the "Later" item "historical timeout recommendations, report-only" (ghatm is the precedent). The issue asks for: sample count, date range, job/matrix matching limitations and a suggested buffer; review before applying a value; historical maxima are not guarantees. All of them are in the output.

What it does

jactionlint --suggest-timeouts (implies --online; --timeout-history-runs N, default 20, 1 to 100; --timeout-buffer FACTOR, default 2, at least 1) reads, for each workflow, the latest successful runs and the jobs of each run, and prints per job: declared timeout-minutes, samples, min, median, max (minutes, from the start on a runner to the end, so the wait for a runner is not in it) and a suggestion. --format json prints the same as a versioned document; other formats are refused.

• Report only. It writes no file and no rule or fix uses its numbers: missing-timeout still never chooses a value (the CONTRIBUTING rule), and default-minutes stays the person's decision. The output ends by saying so, and tells the person the largest suggestion, which is the least that one default-minutes can be without cancelling the slowest job on record.
• The number is ceil(max x buffer) for a job with at least 3 samples. Below that, no number, and the note says why.
• What it states it cannot know: how many runs and which dates (per workflow) and how many samples (per job); runs that failed, were cancelled or were skipped are left out; a matrix is one job whose legs share the timeout (the suggestion is for the slowest leg, the legs are counted); a call of a reusable workflow has no numbers (the timeouts belong to the jobs of the called workflow); job names of the runs that fit no job of the file, or fit two, are listed as "not matched" and are in no number; runs with more than 100 jobs are read in part and the report says so; a lookup that failed (rate limit, 403) makes the report complete: false with the count, and --online=strict fails on it like the other online checks; "runs may predate the current file".
• Matching is by name: the name: (an expression in it matches any text), or the ID, with the matrix values in parentheses that GitHub adds (Unit tests (macos-latest) for name: Unit tests with a matrix; I found that rule by running it against the real API, the first version missed it).

Plumbing

A new optional GitHubRunsClient interface (WorkflowRuns, RunJobs) on the HTTP client (so the cache, ETags, rate limit handling, redaction and the token rules apply as for every other lookup), the fixture client (workflow_runs in the fixtures JSON), and the GitHub Enterprise fallback wrapper (which asks the Server only, like environments: the repository of the workflow is on the Server). The recording client does not record runs. Names are validated before they are put in a path (validWorkflowFile). The repository is GITHUB_REPOSITORY or the origin remote on github.com; githubRepositoryOf now also asks git config when .git is a file (linked work trees and submodules, where it returned nothing; the environment rule uses the same function).

Testing

go vet, go test -race ./..., hk check --all pass locally; the WebAssembly build still compiles. Tests: the name matching (matrix, named, expression names, reusable calls), a fake API with the exact paths and query parameters (status=success, per_page), the numbers (min/median/max, the 8-sample matrix, a failed and a skipped execution that are not samples, 2 samples that get no suggestion, a job that never ran, a call of a workflow, an unmatched name, the buffer), the text, the JSON, an unknown workflow (404), an incomplete run (403 for one run, and --online=strict), the option errors, the fixture client, and that the workflow file is not touched.

Real API: I ran it against the history of jdx/jactionlint itself (the 13 workflows of the repository, 6 runs each and then 20 for two of them, about 100 requests with a token) and read the output: the numbers are plausible, a workflow that never succeeded recently says "no successful run on record", the reusable-workflow call has no numbers, and the matrix of ci.yaml is one job with 3 legs and 60 samples.

Not done / not measured

• It does not follow a reusable workflow into the workflow it calls (it would need the callee's runs, which GitHub lists under the caller's jobs as caller / job); the note says so.
• Pull-request runs from forks, re-runs and runs of other branches are not told apart; "successful runs of any event and branch" is what is read.
• No rate-limit planning beyond what the client has: 1 + N requests per workflow, cached for the hour. Without a token GitHub allows 60 an hour (the docs say to give one).
• The JSON document has no JSON Schema file (the online report has none either); its fields are described in docs/usage.md.

What the series did for #121 (so it can close)

Read against the issue body and the maintainer's comment ("items 1 to 4 done; open: item 5 and the Later list"):

Item	State
1 caller-aware facts	#113 to #118 done earlier; the facts are now exported in one place (#272) with the audit of where they are computed more than once; I did not merge the four token-permission readers (see #272)
2 no-fix reasons	JSON/SARIF done earlier; #269 closes the gap (11 rules had findings with neither a fix nor a reason), adds --show-fix-status and the prerequisites in --explain
3 workflow-secret-scope	done (#136)
4 source invariants	done (#137, #146, #157); #272 and #269 add their commands to the zero-write test
5 online coverage	done by #166, merged after the maintainer's comment: --online-report (any format) and SARIF carry status, skipped lookups by kind, excluded repositories, and the freshness of cached answers (oldestFetched, cacheTtlSeconds, counts of network, cache, stale and immutable answers) with the timestamp source documented
Later: actions.lock compatibility	done (#237, #228)
Later: incremental reporting	#274
Later: installed-version explanations and generated config schema	done (--explain #204, --print-config-schema #195)
Later: versioned semantic export	#272
Later: historical timeout recommendations	this PR

Not done: per-finding freshness (which finding used a cached answer). The cache layer does not know the findings and the rules share memoized answers, so it would be a new tracking path through every online rule for a number the run-level report already bounds; the run-level answers and oldestFetched are what consumers get.

🤖 Generated with Claude Code

---

Note

Medium Risk
New GitHub Actions API traffic and token permissions (Actions read), plus non-trivial job-name matching logic; behavior is report-only and does not modify workflows or lint results.

Overview
Adds --suggest-timeouts, a read-only report mode that turns on online checks, pulls each workflow’s latest successful runs from GitHub, and prints per-job duration stats (min/median/max) plus optional timeout-minutes suggestions. Suggestions use ceil(max × --timeout-buffer) with at least three samples; --timeout-history-runs (1–100, default 20) controls how many runs are fetched. Output is text or json only; nothing is written to workflow files and lint rules are unchanged.

New GitHubRunsClient (WorkflowRuns, RunJobs) extends the existing HTTP client, fixtures, and GHE fallback with the same caching and rate-limit behavior as other online lookups. Linter.SuggestTimeouts() builds the TimeoutReport, matches run job names to workflow jobs (matrix legs, expression names, reusable-workflow calls), and documents gaps (unmatched names, truncated large matrices, incomplete API failures). githubRepositoryOf now resolves origin via git config when .git is a file (worktrees/submodules).

CLI guards reject combining this mode with --fix, --export-facts, --no-online, --changed-since, stdin, and incompatible formats. Docs, man page, and tests cover matching, API queries, JSON/text output, and error cases.

^{Reviewed by Cursor Bugbot for commit fd8189c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features
  • Added --suggest-timeouts to report job durations from recent successful GitHub Actions runs and suggest timeout-minutes values for jobs with enough samples.
  • Added options to choose the number of runs reviewed and set the suggestion buffer. Reports are available in text or JSON and do not modify workflow files.
  • Improved GitHub repository detection for Git worktrees.
• Documentation
  • Documented timeout suggestions, options, report details, and limitations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Central YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 39577122-f368-42d0-8942-50b62fcb6f11

📥 Commits

Reviewing files that changed from the base of the PR and between 0190b4c and fd8189c.

📒 Files selected for processing: 5

• command.go
• command_options.go
• docs/usage.md
• man/jactionlint.1.ronn
• timeout_history_test.go

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📝 Walkthrough

The change adds GitHub workflow-run and job lookups, a timeout-history report API, and CLI options to display duration samples and timeout suggestions. Reports support text and JSON output. The tool does not write suggested timeout values to workflow files.

Changes: Timeout Suggestions

Layer / File(s)	Summary
GitHub run-history access github_runs.go, github_runs_http.go, github_session.go, github_fixture.go	Adds run and job lookup types and client methods. HTTP, fixture, fallback, and online-session implementations provide lookup data, with session caching.
Timeout report generation timeout_history.go, project.go, timeout_history_test.go, docs/api.md, docs/checks.md	Adds SuggestTimeouts to match workflow jobs with successful run data and report duration statistics. Suggestions require at least three successful samples and use the longest duration with the configured buffer. Repository resolution can read a GitHub URL from Git when .git/config cannot be read. Tests cover matching, output, validation, and incomplete lookups.
CLI options and report output command.go, command_options.go, docs/usage.md, man/jactionlint.1.ronn	Adds --suggest-timeouts, --timeout-history-runs, and --timeout-buffer. The CLI validates option combinations, enables online mode for suggestions, and writes text or JSON output.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant Linter
  participant OnlineSession
  participant GitHubRunsClient
  User->>CLI: request timeout suggestions
  CLI->>Linter: call SuggestTimeouts
  Linter->>OnlineSession: request workflow runs and job details
  OnlineSession->>GitHubRunsClient: retrieve successful runs and job data
  GitHubRunsClient-->>OnlineSession: return run and job data
  OnlineSession-->>Linter: return lookup results
  Linter-->>CLI: return timeout report
  CLI-->>User: write text or JSON report

Loading

Merge Risk: ⚪ Minimal · up to fd818

The supplied evidence identifies no issue that needs to be resolved before merging.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 43.75% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 9 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: adding --suggest-timeouts to report actual job durations from recent runs.
Linked Issues check		Issue #121 is closed and completed, so it provides historical context only. No active directly linked coding requirements apply. The reported implementation covers the historical timeout-reporting ite…
Out of Scope Changes check		The changes support the timeout-history report. CLI options, GitHub run lookups, fixture and fallback clients, repository detection, documentation, and tests are connected to that report. The report d…

Full details: Docstring Coverage

Explanation

Docstring coverage is 43.75% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 9 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3e73cb9. Configure here.}