Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/quiet-queues-time.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'grafana-github-datasource': minor
---

Add a Merge Queue Timings query to visualize how long pull requests spend in GitHub's merge queue.
23 changes: 23 additions & 0 deletions docs/sources/query-editor.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ Select a query type from the **Query Type** drop-down in the query editor:
- [**Deployments**](#deployments): List deployments for a repository, including environment, ref, and task information.
- [**Issues**](#issues): List issues in a repository, using the GitHub query syntax to filter the response.
- [**Labels**](#labels): List labels defined in a repository.
- [**Merge queue timings**](#merge-queue-timings): Measure how long each pull request attempt spent in GitHub's merge queue.
- [**Milestones**](#milestones): Retrieve milestones for a repository, which can be used to group issues and pull requests.
- [**Packages**](#packages): List packages published from a repository in an organization.
- [**Projects**](#projects): List projects associated with a user or organization.
Expand Down Expand Up @@ -426,6 +427,28 @@ Show all labels for the `grafana/grafana` repository:
| color | Hexadecimal number |
| description | Label description |

### Merge queue timings

Measure how long pull requests spend in GitHub's merge queue. Select **Merge Queue Timings** and set **Owner** and **Repository**. The query reads queue entry and removal events from each pull request's [GitHub timeline](https://docs.github.com/en/graphql/reference/pulls), rather than using workflow run or check run timestamps.

The Grafana time range selects pull requests by their **last updated** timestamp. For each matching pull request, the query returns its full queue history, including attempts outside the selected range. A subsequent update can move a pull request out of a historical selection. GitHub search returns up to 1,000 matching pull requests, so use a narrower range for busy repositories.

#### Response

The table contains one row per queue attempt. A pull request that leaves and re-enters the queue has multiple rows; a pull request that never entered the queue has none.

| Name | Description |
|------|-------------|
| `repository` | Repository in `owner/name` format |
| `pull_request_number` | Pull request number |
| `pull_request_url` | Link to the pull request |
| `enqueued_at` | Timestamp of the queue entry |
| `exited_at` | Timestamp of the matching queue removal, or null if no removal was recorded |
| `exit_reason` | Removal reason reported by GitHub, such as `merged`, or null if unavailable |
| `duration_seconds` | Seconds between queue entry and removal, or null for an attempt with no matching removal |

To see the distribution of time spent in the queue, use a **Histogram** panel with the `duration_seconds` field. To compare merged attempts only, add a **Filter data by values** transformation that keeps rows where `exit_reason` is `merged`. This measures total time in the queue, not time spent running individual checks.

### Milestones

Retrieve milestones for a repository, which can be used to group issues and pull requests.
Expand Down
141 changes: 141 additions & 0 deletions pkg/github/merge_queue_timings.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
package github

import (
"context"
"fmt"
"strings"
"time"

"github.com/grafana/github-datasource/pkg/models"
"github.com/grafana/grafana-plugin-sdk-go/data"
"github.com/shurcooL/githubv4"
)

type mergeQueueTimeline struct {
Nodes []struct {
Type string `graphql:"__typename"`
Added struct {
CreatedAt githubv4.DateTime
} `graphql:"... on AddedToMergeQueueEvent"`
Removed struct {
CreatedAt githubv4.DateTime
Reason *string
} `graphql:"... on RemovedFromMergeQueueEvent"`
}
PageInfo models.PageInfo
}

type mergeQueueSearch struct {
Search struct {
Nodes []struct {
PullRequest struct {
ID githubv4.ID
Number int64
URL string
Timeline mergeQueueTimeline `graphql:"timelineItems(first: 20, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT])"`
} `graphql:"... on PullRequest"`
}
PageInfo models.PageInfo
} `graphql:"search(query: $query, type: ISSUE, first: 50, after: $searchCursor)"`
}

type mergeQueueTimelinePage struct {
Node struct {
PullRequest struct {
Timeline mergeQueueTimeline `graphql:"timelineItems(first: 100, after: $timelineCursor, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT])"`
} `graphql:"... on PullRequest"`
} `graphql:"node(id: $id)"`
}

type mergeQueueAttempt struct {
Number int64
URL string
EnqueuedAt time.Time
ExitedAt *time.Time
ExitReason *string
}

type mergeQueueTimings struct {
repository string
attempts []mergeQueueAttempt
}

func (m mergeQueueTimings) Frames() data.Frames {
duration := data.NewField("duration_seconds", nil, []*float64{})
duration.Config = &data.FieldConfig{Unit: "s"}
frame := data.NewFrame("merge_queue_timings",
data.NewField("repository", nil, []string{}),
data.NewField("pull_request_number", nil, []int64{}),
data.NewField("pull_request_url", nil, []string{}),
data.NewField("enqueued_at", nil, []time.Time{}),
data.NewField("exited_at", nil, []*time.Time{}),
data.NewField("exit_reason", nil, []*string{}),
duration,
)
for _, attempt := range m.attempts {
var seconds *float64
if attempt.ExitedAt != nil {
value := attempt.ExitedAt.Sub(attempt.EnqueuedAt).Seconds()
seconds = &value
}
frame.AppendRow(m.repository, attempt.Number, attempt.URL, attempt.EnqueuedAt, attempt.ExitedAt, attempt.ExitReason, seconds)
}
return data.Frames{frame}
}

type mergeQueueQuerier interface {
Query(context.Context, any, map[string]any) error
}

// GetMergeQueueTimings finds PRs updated in the time range and reconstructs their queue attempts from timeline events.
func GetMergeQueueTimings(ctx context.Context, client mergeQueueQuerier, owner, repo string, from, to time.Time) (mergeQueueTimings, error) {
result := mergeQueueTimings{repository: owner + "/" + repo}
if strings.TrimSpace(owner) == "" || strings.TrimSpace(repo) == "" || from.IsZero() || to.Before(from) {
return result, nil
}

search := fmt.Sprintf("is:pr repo:%s updated:%s..%s", result.repository, from.UTC().Format(time.RFC3339), to.UTC().Format(time.RFC3339))
variables := map[string]any{"query": githubv4.String(search), "searchCursor": (*githubv4.String)(nil)}
for {
var page mergeQueueSearch
if err := client.Query(ctx, &page, variables); err != nil {
return result, fmt.Errorf("searching for pull requests in %s: %w", result.repository, err)
}
for _, node := range page.Search.Nodes {
pr := node.PullRequest
timeline := pr.Timeline
// Keep the pending enqueue across timeline pages, but never across PRs.
pending := -1
for {
for _, event := range timeline.Nodes {
switch event.Type {
case "AddedToMergeQueueEvent":
if !event.Added.CreatedAt.IsZero() {
pending = len(result.attempts)
result.attempts = append(result.attempts, mergeQueueAttempt{Number: pr.Number, URL: pr.URL, EnqueuedAt: event.Added.CreatedAt.Time})
}
case "RemovedFromMergeQueueEvent":
if pending >= 0 && !event.Removed.CreatedAt.Before(result.attempts[pending].EnqueuedAt) {
attempt := &result.attempts[pending]
attempt.ExitedAt = &event.Removed.CreatedAt.Time
attempt.ExitReason = event.Removed.Reason
pending = -1
}
}
}
if !timeline.PageInfo.HasNextPage {
break
}
var next mergeQueueTimelinePage
if err := client.Query(ctx, &next, map[string]any{"id": pr.ID, "timelineCursor": &timeline.PageInfo.EndCursor}); err != nil {
return result, fmt.Errorf("reading merge queue timeline for %s#%d: %w", result.repository, pr.Number, err)
}
timeline = next.Node.PullRequest.Timeline
}
}
if !page.Search.PageInfo.HasNextPage {
return result, nil
}
variables["searchCursor"] = &page.Search.PageInfo.EndCursor
}
}
21 changes: 21 additions & 0 deletions pkg/github/merge_queue_timings_handler.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
package github

import (
"context"

"github.com/grafana/github-datasource/pkg/dfutil"
"github.com/grafana/github-datasource/pkg/models"
"github.com/grafana/grafana-plugin-sdk-go/backend"
)

// HandleMergeQueueTimings handles plugin queries for GitHub merge queue attempts.
func (s *QueryHandler) HandleMergeQueueTimings(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
responses := processQueries(ctx, req, func(ctx context.Context, q backend.DataQuery) backend.DataResponse {
var query models.Query
if err := UnmarshalQuery(q.JSON, &query); err != nil {
return *err
}
return dfutil.FrameResponseWithError(GetMergeQueueTimings(ctx, s.Datasource.client, query.Owner, query.Repository, q.TimeRange.From, q.TimeRange.To))
})
return &backend.QueryDataResponse{Responses: responses}, nil
}
75 changes: 75 additions & 0 deletions pkg/github/merge_queue_timings_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
package github

import (
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"testing"
"time"

"github.com/shurcooL/githubv4"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestGetMergeQueueTimings(t *testing.T) {
from := time.Date(2026, 11, 17, 0, 0, 0, 0, time.UTC)
to := from.Add(24 * time.Hour)
requests := make(chan string, 4)
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var request struct {
Query string
Variables map[string]any
}
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
t.Error(err)
w.WriteHeader(http.StatusBadRequest)
return
}
w.Header().Set("Content-Type", "application/json")
switch {
case request.Variables["query"] != nil && request.Variables["searchCursor"] == nil:
requests <- "first search page"
assert.Equal(t, "is:pr repo:github/docs updated:2026-11-17T00:00:00Z..2026-11-18T00:00:00Z", request.Variables["query"])
assert.Contains(t, request.Query, "ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT")
fmt.Fprint(w, `{"data":{"search":{"nodes":[{"id":"PR_1","number":1,"url":"https://github.com/github/docs/pull/1","timelineItems":{"nodes":[{"__typename":"AddedToMergeQueueEvent","createdAt":"2026-11-17T08:00:00Z"}],"pageInfo":{"hasNextPage":true,"endCursor":"more-events"}}}],"pageInfo":{"hasNextPage":true,"endCursor":"more-prs"}}}}`)
case request.Variables["timelineCursor"] == "more-events":
requests <- "next timeline page"
assert.Equal(t, "PR_1", request.Variables["id"])
assert.Contains(t, request.Query, "$id:ID!")
fmt.Fprint(w, `{"data":{"node":{"timelineItems":{"nodes":[{"__typename":"RemovedFromMergeQueueEvent","createdAt":"2026-11-17T08:01:30Z","reason":"failed checks"},{"__typename":"AddedToMergeQueueEvent","createdAt":"2026-11-17T08:45:01Z"},{"__typename":"RemovedFromMergeQueueEvent","createdAt":"2026-11-17T08:50:56Z","reason":"merged"}],"pageInfo":{"hasNextPage":false}}}}}`)
case request.Variables["searchCursor"] == "more-prs":
requests <- "next search page"
fmt.Fprint(w, `{"data":{"search":{"nodes":[{"id":"PR_2","number":2,"url":"https://github.com/github/docs/pull/2","timelineItems":{"nodes":[{"__typename":"AddedToMergeQueueEvent","createdAt":"2026-11-17T09:00:00Z"}],"pageInfo":{"hasNextPage":false}}},{"id":"PR_3","number":3,"url":"https://github.com/github/docs/pull/3","timelineItems":{"nodes":[],"pageInfo":{"hasNextPage":false}}}],"pageInfo":{"hasNextPage":false}}}}`)
default:
t.Errorf("unexpected query: %s (%v)", request.Query, request.Variables)
w.WriteHeader(http.StatusBadRequest)
}
}))
defer server.Close()

result, err := GetMergeQueueTimings(t.Context(), githubv4.NewEnterpriseClient(server.URL, server.Client()), "github", "docs", from, to)
require.NoError(t, err)
require.Len(t, requests, 3)
frames := result.Frames()
require.Len(t, frames, 1)
frame := frames[0]
require.Equal(t, "merge_queue_timings", frame.Name)
require.Equal(t, 3, frame.Rows())
require.Len(t, frame.Fields, 7)
assert.Equal(t, "github/docs", frame.Fields[0].At(1))
assert.Equal(t, int64(1), frame.Fields[1].At(1))
assert.Equal(t, "https://github.com/github/docs/pull/1", frame.Fields[2].At(1))
assert.Equal(t, "duration_seconds", frame.Fields[6].Name)
assert.Equal(t, "s", frame.Fields[6].Config.Unit)
assert.Equal(t, 90.0, *frame.Fields[6].At(0).(*float64))
assert.Equal(t, "failed checks", *frame.Fields[5].At(0).(*string))
assert.Equal(t, 355.0, *frame.Fields[6].At(1).(*float64))
assert.Equal(t, "merged", *frame.Fields[5].At(1).(*string))
assert.Equal(t, from.Add(8*time.Hour+45*time.Minute+time.Second), frame.Fields[3].At(1))
assert.Equal(t, int64(2), frame.Fields[1].At(2))
assert.Nil(t, frame.Fields[4].At(2))
assert.Nil(t, frame.Fields[5].At(2))
assert.Nil(t, frame.Fields[6].At(2))
}
1 change: 1 addition & 0 deletions pkg/github/query_handler.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ func GetQueryHandlers(s *QueryHandler) *datasource.QueryTypeMux {
register(models.QueryTypeContributors, s.HandleContributors)
register(models.QueryTypeLabels, s.HandleLabels)
register(models.QueryTypePullRequests, s.HandlePullRequests)
register(models.QueryTypeMergeQueueTimings, s.HandleMergeQueueTimings)
register(models.QueryTypePullRequestReviews, s.HandlePullRequestReviews)
register(models.QueryTypeReleases, s.HandleReleases)
register(models.QueryTypeTags, s.HandleTags)
Expand Down
2 changes: 2 additions & 0 deletions pkg/models/query.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ const (
QueryTypeReleases QueryType = "Releases"
// QueryTypePullRequests is used when querying pull requests in a GitHub repository
QueryTypePullRequests QueryType = "Pull_Requests"
// QueryTypeMergeQueueTimings is used when querying pull request merge queue attempts.
QueryTypeMergeQueueTimings QueryType = "Merge_Queue_Timings"
// QueryTypePullRequestReviews is used when querying pull request reviews in a GitHub repository
QueryTypePullRequestReviews = "Pull_Request_Reviews"
// QueryTypeLabels is used when querying labels in a GitHub repository
Expand Down
1 change: 1 addition & 0 deletions src/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ export const QueryTypes = [
'Tags',
'Branches',
'Releases',
'Merge_Queue_Timings',
'Pull_Requests',
'Pull_Requests_For_Branches',
'Pull_Request_Reviews',
Expand Down
3 changes: 3 additions & 0 deletions src/types/query.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ export type Pull_RequestsOptions = Options & {
type Pull_RequestsQuery = BaseQuery<'Pull_Requests', Pull_RequestsOptions>
//#endregion

type Merge_Queue_TimingsQuery = BaseQuery<'Merge_Queue_Timings', {}>

//#region Pull_Requests_For_Branches Query
export type Pull_Requests_For_BranchesOptions = Options & {
branches?: string[];
Expand Down Expand Up @@ -212,6 +214,7 @@ export type GitHubQuery =
ContributorsQuery |
TagsQuery |
ReleasesQuery |
Merge_Queue_TimingsQuery |
Pull_RequestsQuery |
Pull_Requests_For_BranchesQuery |
Pull_Request_ReviewsQuery |
Expand Down
19 changes: 19 additions & 0 deletions src/validation.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
import { isValid } from './validation';
import type { GitHubQuery } from './types/query';

const query: GitHubQuery = {
refId: 'A',
queryType: 'Merge_Queue_Timings',
owner: 'github',
repository: 'docs',
};

describe('Merge Queue Timings query validation', () => {
it('accepts an owner and repository without extra options', () => {
expect(isValid(query)).toBe(true);
});

it.each(['owner', 'repository'] as const)('requires %s', (key) => {
expect(isValid({ ...query, [key]: undefined })).toBe(false);
});
});
1 change: 1 addition & 0 deletions src/validation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ export const isValid = (query: GitHubQuery): boolean => {
query.queryType === "Commits" ||
query.queryType === 'Commit_Files' ||
query.queryType === 'Check_Runs' ||
query.queryType === 'Merge_Queue_Timings' ||
query.queryType === "Contributors" ||
query.queryType === "Tags" ||
query.queryType === "Releases" ||
Expand Down
1 change: 1 addition & 0 deletions src/views/QueryEditor.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ const queryEditors: Record<QueryType, { component: (props: Props, onChange: (val
),
},
['Releases']: { component: () => <></> },
['Merge_Queue_Timings']: { component: () => <></> },
['Vulnerabilities']: { component: () => <></> },
['Stargazers']: { component: () => <></> },
['Labels']: {
Expand Down
Loading