Skip to content

feat: add Check Runs query type - #802

Open
pkucia wants to merge 4 commits into
grafana:mainfrom
pkucia:feat/check-runs-query-type
Open

feat: add Check Runs query type#802
pkucia wants to merge 4 commits into
grafana:mainfrom
pkucia:feat/check-runs-query-type

Conversation

@pkucia

@pkucia pkucia commented Aug 20, 2026

Copy link
Copy Markdown

Summary

Adds a Check Runs query type that lists the check runs reported against a git reference, backed by
GET /repos/{owner}/{repo}/commits/{ref}/check-runs.

Check runs are the individual checks that GitHub Apps report against a commit: GitHub Actions jobs, external CI,
linters. There is currently no way to see them in Grafana. Workflow Runs covers GitHub Actions at the workflow
level, but not the per-check results that show up on a commit or PR, and not checks reported by other apps.

This makes it possible to build CI health dashboards per commit or branch, such as pass/fail rates by check name and
check latency over time.

Options are Owner, Repository and Ref (required), plus optional Check name, Status and Filter. Filtering is delegated
to the GitHub API rather than done client side, and empty options are omitted from the request so GitHub's own
defaults apply. Full option and response documentation is in docs/sources/query-editor.md.

May partially help #326, since check runs map roughly to jobs and the frame includes a duration per check run.

Implementation

Backend (Go):

  • pkg/models/checkruns.goCheckRunsOptions, with the usual WithRepo variant
  • pkg/github/checkruns.go — paginated fetch and frame construction, following Code Scanning for the client
    pattern and Commit Files for the ref scoped shape
  • pkg/github/checkruns_handler.go, datasource.go, query_handler.go — handler wired into the query mux
  • pkg/github/client/client.goListCheckRunsForRef added to the REST client and the Client interface

Uses Checks.ListCheckRunsForRef from go-github, which is already a direct dependency, so there are no new
dependencies.

Frontend (TypeScript/React):

  • src/views/QueryEditorCheckRuns.tsx — editor for ref, check name, status and filter
  • src/types/query.ts, src/constants.ts, src/validation.tsCheckRunsOptions type and registration

Docs:

  • docs/sources/query-editor.md — list entry plus a ### Check runs reference section

One thing worth flagging: I did not register this in schema.go. The other ref scoped query types (Commit Files,
Pull Request Files, Branches) are not registered either, since there is no table parameter for a free text git
ref, so I followed that precedent. Happy to add it if you would prefer.

completed_at and duration_seconds are nullable so that in flight check runs are represented honestly rather than
with zero values. duration_seconds is derived rather than a raw API field; I can drop it if you would rather keep
the frame a straight mirror of the API.

The editor uses Combobox rather than the deprecated Select, in line with #324.

Test plan

  • go test ./...
  • yarn test:ci, yarn typecheck, yarn lint, yarn spellcheck, yarn build
  • Unit tests for frame construction, pagination, the empty input guard, and filter passthrough, plus a golden
    file for the check_runs frame
  • Client tests driving the real go-github client against a mock server, asserting request path, query
    parameters and response parsing
  • Frontend test for the new query editor
  • Verified against a live Grafana 12.2.0 instance querying real check runs from this repository, covering commit
    SHA refs, heads/<branch> refs, and the check name, status and filter options

Check Suites and the legacy Combined Status endpoint are deliberately out of scope to keep this reviewable. Happy to
follow up with those separately if there is interest.

pkucia added 4 commits August 20, 2026 09:21
Adds support for listing GitHub check runs for a git reference via
GET /repos/{owner}/{repo}/commits/{ref}/check-runs.

The query is ref-scoped and supports optional filtering by check name,
status and the GitHub 'filter' parameter (latest/all). Results are
paginated and flattened into a check_runs data frame, including a
derived duration_seconds field for CI latency dashboards.
Adds the Check_Runs query type to the query editor with inputs for the
git ref, an optional check name, and comboboxes for status and the
latest/all filter.
Adds the Check Runs query type to the query editor documentation and a
changeset entry for the release notes.
Adds tests that exercise the real go-github client against a mock GitHub
server to confirm the request path, query parameters, and response
parsing for the check runs endpoint.
@pkucia
pkucia requested a review from a team as a code owner August 20, 2026 08:10
@cla-assistant

cla-assistant Bot commented Aug 20, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant