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/short-steps-run.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'grafana-github-datasource': minor
---

Query workflow runs across a repository without selecting a workflow, and analyze individual GitHub Actions job step durations.
17 changes: 13 additions & 4 deletions docs/sources/query-editor.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ Select a query type from the **Query Type** drop-down in the query editor:
- [**Vulnerabilities**](#vulnerabilities): Query security vulnerabilities detected in a repository.
- [**Webhook deliveries**](#webhook-deliveries): List deliveries of an organization or repository webhook, including the response status code.
- [**Workflows**](#workflows): List GitHub Actions workflows defined in a repository.
- [**Workflow runs**](#workflow-runs): List runs for a specific workflow, including status, conclusion, and timing information.
- [**Workflow runs**](#workflow-runs): List runs across a repository or filter by workflow, including status, conclusion, and timing information.
- [**Workflow job steps**](#workflow-job-steps): List individual job steps and their durations across workflow runs.
- [**Workflow usage**](#workflow-usage): Retrieve usage statistics for a workflow, such as run counts and durations.

### Code scanning
Expand Down Expand Up @@ -1045,20 +1046,22 @@ Show all workflows created within the `grafana/grafana` repository within the cu

### Workflow runs

List runs for a specific workflow, including status, conclusion, and timing information.
List runs across a repository or filter by a specific workflow. The Grafana time range selects runs by creation time. GitHub limits time-filtered results to 1,000 runs; use a narrower range for busy repositories.

#### Query options

| Name | Description | Required |
|------|-------------|----------|
| Owner | GitHub user or organization that owns the repository | Yes |
| Repository | Name of the repository | Yes |
| Workflow | The workflow ID or file name. Use `id` or the filename from `path` from [Workflows](#workflows) queries. | Yes |
| Workflow | Leave empty for all workflows, or enter a workflow ID or file name from [Workflows](#workflows). | No |
| Branch | The head branch to filter on | No |

##### Sample queries

Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository:
To compare run outcomes across a repository, set **Owner** and **Repository**, and leave **Workflow** and **Branch** empty. In the panel, use **Group by** on `conclusion` and **Count** on `id`. To compare workflows side by side, also group by `workflow_id`.

Show runs for the `Levitate` workflow in the `grafana/grafana` repository:

- Owner: `grafana`
- Repository: `grafana`
Expand Down Expand Up @@ -1090,6 +1093,12 @@ Show workflow runs for a specific branch (useful for monitoring release branch C
| workflow_id | Unique identifier for the workflow definition |
| run_number | The run number for this workflow run in the repository |

### Workflow job steps

List individual steps for the latest attempt of each matching workflow run. Use the same owner, repository, optional workflow and branch filters, and run creation time range as [Workflow runs](#workflow-runs). This detail query fetches jobs separately for each run, so it inspects at most the 50 most recent matching runs and reports a warning if the result is truncated. Use **Workflow Runs** for repository-wide run counts.

The table contains one row per step and includes workflow, run and attempt, job and link, step number and name, status, conclusion, start and completion times, and `duration_seconds`. Skipped steps and steps without valid start and completion times have no duration. For a bottleneck panel, group by `workflow_name`, `job_name`, and `step_name`, then calculate the mean or maximum duration.

### Workflow usage

Retrieve usage statistics for a workflow, such as run counts and durations.
Expand Down
43 changes: 25 additions & 18 deletions pkg/github/client/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"net/http"
"net/url"
"strconv"
"strings"
"time"

"github.com/bradleyfalzon/ghinstallation/v2"
Expand Down Expand Up @@ -407,6 +408,15 @@ func (client *Client) getWorkflowUsage(ctx context.Context, owner, repo string,
return client.restClient.Actions.GetWorkflowUsageByFileName(ctx, owner, repo, workflow)
}

// ListWorkflowJobs lists a page of jobs and their steps for an Actions run.
func (client *Client) ListWorkflowJobs(ctx context.Context, owner, repo string, id int64, opts *googlegithub.ListWorkflowJobsOptions) (*googlegithub.Jobs, *googlegithub.Response, error) {
jobs, response, err := client.restClient.Actions.ListWorkflowJobs(ctx, owner, repo, id, opts)
if err != nil {
return nil, response, addErrorSourceToError(err, response)
}
return jobs, response, nil
}

func (client *Client) GetWorkflowRuns(ctx context.Context, owner, repo, workflow string, branch string, timeRange backend.TimeRange) ([]*googlegithub.WorkflowRun, error) {
workflowRuns := []*googlegithub.WorkflowRun{}

Expand All @@ -426,10 +436,9 @@ func (client *Client) GetWorkflowRuns(ctx context.Context, owner, repo, workflow
}

func (client *Client) getWorkflowRuns(ctx context.Context, owner, repo, workflow string, branch string, timeRange backend.TimeRange, page int) ([]*googlegithub.WorkflowRun, int, error) {
workflow = strings.TrimSpace(workflow)
workflowID, _ := strconv.ParseInt(workflow, 10, 64)

workflowRuns := []*googlegithub.WorkflowRun{}

format := time.RFC3339
created := fmt.Sprintf("%s..%s", timeRange.From.Format(format), timeRange.To.Format(format))

Expand All @@ -439,29 +448,27 @@ func (client *Client) getWorkflowRuns(ctx context.Context, owner, repo, workflow
err error
)

if workflowID > 0 {
runs, response, err = client.restClient.Actions.ListWorkflowRunsByID(ctx, owner, repo, workflowID, &googlegithub.ListWorkflowRunsOptions{
Created: created,
ListOptions: googlegithub.ListOptions{Page: page, PerPage: 100},
Branch: branch,
})
} else {
runs, response, err = client.restClient.Actions.ListWorkflowRunsByFileName(ctx, owner, repo, workflow, &googlegithub.ListWorkflowRunsOptions{
Created: created,
ListOptions: googlegithub.ListOptions{Page: page, PerPage: 100},
Branch: branch,
})
opts := &googlegithub.ListWorkflowRunsOptions{
Created: created,
ListOptions: googlegithub.ListOptions{Page: page, PerPage: 100},
Branch: branch,
}
switch {
case workflow == "":
runs, response, err = client.restClient.Actions.ListRepositoryWorkflowRuns(ctx, owner, repo, opts)
case workflowID > 0:
runs, response, err = client.restClient.Actions.ListWorkflowRunsByID(ctx, owner, repo, workflowID, opts)
default:
runs, response, err = client.restClient.Actions.ListWorkflowRunsByFileName(ctx, owner, repo, workflow, opts)
}

if err != nil {
// If the workflow is not found, return a specific error.
if response != nil && response.StatusCode == http.StatusNotFound {
if workflow != "" && response != nil && response.StatusCode == http.StatusNotFound {
return nil, 0, backend.DownstreamError(errWorkflowNotFound)
}
return nil, 0, addErrorSourceToError(fmt.Errorf("fetching workflow runs: %w", err), response)
}

workflowRuns = append(workflowRuns, runs.WorkflowRuns...)

return workflowRuns, response.NextPage, nil
return runs.WorkflowRuns, response.NextPage, nil
}
61 changes: 61 additions & 0 deletions pkg/github/client/workflow_runs_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
package githubclient

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

googlegithub "github.com/google/go-github/v84/github"
"github.com/grafana/grafana-plugin-sdk-go/backend"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestGetWorkflowRunsEndpoints(t *testing.T) {
const base = "/api/v3/repos/acme/widget/actions/"
for _, tc := range []struct {
name, workflow, path string
}{
{"all workflows", "", base + "runs"},
{"blank workflow", " ", base + "runs"},
{"by id", "42", base + "workflows/42/runs"},
{"by filename", "ci.yml", base + "workflows/ci.yml/runs"},
} {
t.Run(tc.name, func(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != tc.path {
t.Errorf("request path = %q, want %q", r.URL.Path, tc.path)
w.WriteHeader(http.StatusNotFound)
return
}
params := r.URL.Query()
assert.Equal(t, "main", params.Get("branch"))
assert.Equal(t, "100", params.Get("per_page"))
assert.Equal(t, "2026-11-16T00:00:00Z..2026-11-17T00:00:00Z", params.Get("created"))
w.Header().Set("Content-Type", "application/json")
switch params.Get("page") {
case "1":
w.Header().Set("Link", fmt.Sprintf("<http://%s%s?page=2>; rel=\"next\"", r.Host, r.URL.Path))
fmt.Fprint(w, `{"total_count":2,"workflow_runs":[{"id":11,"workflow_id":42}]}`)
case "2":
fmt.Fprint(w, `{"total_count":2,"workflow_runs":[{"id":12,"workflow_id":43}]}`)
default:
t.Errorf("unexpected page %q", params.Get("page"))
w.WriteHeader(http.StatusBadRequest)
}
}))
defer server.Close()
rest, err := googlegithub.NewClient(server.Client()).WithEnterpriseURLs(server.URL, server.URL)
require.NoError(t, err)
client := &Client{restClient: rest}
from := time.Date(2026, 11, 16, 0, 0, 0, 0, time.UTC)
runs, err := client.GetWorkflowRuns(t.Context(), "acme", "widget", tc.workflow, "main", backend.TimeRange{From: from, To: from.Add(24 * time.Hour)})
require.NoError(t, err)
require.Len(t, runs, 2)
assert.Equal(t, int64(11), runs[0].GetID())
assert.Equal(t, int64(43), runs[1].GetWorkflowID())
})
}
}
1 change: 1 addition & 0 deletions pkg/github/query_handler.go
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ func GetQueryHandlers(s *QueryHandler) *datasource.QueryTypeMux {
register(models.QueryTypeWorkflows, s.HandleWorkflows)
register(models.QueryTypeWorkflowUsage, s.HandleWorkflowUsage)
register(models.QueryTypeWorkflowRuns, s.HandleWorkflowRuns)
register(models.QueryTypeWorkflowJobSteps, s.HandleWorkflowJobSteps)
register(models.QueryTypeCodeScanning, s.HandleCodeScanning)
register(models.QueryTypeDeployments, s.HandleDeployments)
register(models.QueryTypeOrganizations, s.HandleOrganizations)
Expand Down
115 changes: 115 additions & 0 deletions pkg/github/workflow_job_steps.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
package github

import (
"context"
"fmt"
"time"

googlegithub "github.com/google/go-github/v84/github"
"github.com/grafana/grafana-plugin-sdk-go/backend"
"github.com/grafana/grafana-plugin-sdk-go/data"
)

const workflowJobStepsRunLimit = 50

type workflowJob struct {
run *googlegithub.WorkflowRun
job *googlegithub.WorkflowJob
}

type workflowJobSteps []workflowJob

func (jobs workflowJobSteps) Frames() data.Frames {
duration := data.NewField("duration_seconds", nil, []*float64{})
duration.Config = &data.FieldConfig{Unit: "s"}
frame := data.NewFrame("workflow_job_steps",
data.NewField("workflow_id", nil, []int64{}),
data.NewField("workflow_name", nil, []string{}),
data.NewField("run_id", nil, []int64{}),
data.NewField("run_attempt", nil, []int64{}),
data.NewField("job_id", nil, []int64{}),
data.NewField("job_name", nil, []string{}),
data.NewField("job_url", nil, []string{}),
data.NewField("step_number", nil, []int64{}),
data.NewField("step_name", nil, []string{}),
data.NewField("status", nil, []string{}),
data.NewField("conclusion", nil, []string{}),
data.NewField("started_at", nil, []*time.Time{}),
data.NewField("completed_at", nil, []*time.Time{}),
duration,
)
frame.Meta = &data.FrameMeta{PreferredVisualization: data.VisTypeTable}
for _, row := range jobs {
for _, step := range row.job.Steps {
if step == nil {
continue
}
start, end := step.StartedAt.GetTime(), step.CompletedAt.GetTime()
var seconds *float64
if step.GetConclusion() != "skipped" && start != nil && end != nil && !start.IsZero() && !end.Before(*start) {
seconds = googlegithub.Ptr(end.Sub(*start).Seconds())
}
frame.AppendRow(row.run.GetWorkflowID(), row.run.GetName(), row.run.GetID(), row.job.GetRunAttempt(),
row.job.GetID(), row.job.GetName(), row.job.GetHTMLURL(), step.GetNumber(), step.GetName(),
step.GetStatus(), step.GetConclusion(), start, end, seconds)
}
}
return data.Frames{frame}
}

type workflowJobStepsResult struct {
jobs workflowJobSteps
truncated bool
}

func (r workflowJobStepsResult) Frames() data.Frames {
frames := r.jobs.Frames()
if r.truncated {
frames[0].Meta.Notices = []data.Notice{{
Severity: data.NoticeSeverityWarning,
Text: fmt.Sprintf("Showing job steps for the %d most recent matching workflow runs. Narrow the time range or set a branch or workflow filter.", workflowJobStepsRunLimit),
}}
}
return frames
}

type workflowJobStepsClient interface {
GetWorkflowRuns(context.Context, string, string, string, string, backend.TimeRange) ([]*googlegithub.WorkflowRun, error)
ListWorkflowJobs(context.Context, string, string, int64, *googlegithub.ListWorkflowJobsOptions) (*googlegithub.Jobs, *googlegithub.Response, error)
}

func getWorkflowJobSteps(ctx context.Context, client workflowJobStepsClient, owner, repo, workflow, branch string, timeRange backend.TimeRange) (workflowJobStepsResult, error) {
var result workflowJobStepsResult
if owner == "" || repo == "" {
return result, nil
}
runs, err := client.GetWorkflowRuns(ctx, owner, repo, workflow, branch, timeRange)
if err != nil {
return result, err
}
if len(runs) > workflowJobStepsRunLimit {
result.truncated = true
runs = runs[:workflowJobStepsRunLimit]
}
for _, run := range runs {
if run == nil || run.GetID() == 0 {
continue
}
for page := 1; page != 0; {
jobs, response, err := client.ListWorkflowJobs(ctx, owner, repo, run.GetID(), &googlegithub.ListWorkflowJobsOptions{
Filter: "latest",
ListOptions: googlegithub.ListOptions{Page: page, PerPage: 100},
})
if err != nil {
return workflowJobStepsResult{}, fmt.Errorf("listing jobs for workflow run %d: %w", run.GetID(), err)
}
for _, job := range jobs.Jobs {
if job != nil {
result.jobs = append(result.jobs, workflowJob{run: run, job: job})
}
}
page = response.NextPage
}
}
return result, nil
}
32 changes: 32 additions & 0 deletions pkg/github/workflow_job_steps_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
package github

import (
"encoding/json"
"testing"

googlegithub "github.com/google/go-github/v84/github"
"github.com/stretchr/testify/require"
)

func TestWorkflowJobStepsFrame(t *testing.T) {
var job googlegithub.WorkflowJob
require.NoError(t, json.Unmarshal([]byte(`{"id":45,"name":"Build (linux)","run_attempt":2,"steps":[{"name":"Build","number":1,"status":"completed","conclusion":"success","started_at":"2026-11-17T08:00:00Z","completed_at":"2026-11-17T08:02:30Z"},{"name":"Publish","number":2,"status":"in_progress","started_at":"2026-11-17T08:03:00Z"},{"name":"Optional","number":3,"status":"completed","conclusion":"skipped","started_at":"2026-11-17T08:03:00Z","completed_at":"2026-11-17T08:03:00Z"}]}`), &job))
run := &googlegithub.WorkflowRun{ID: googlegithub.Ptr(int64(12)), WorkflowID: googlegithub.Ptr(int64(34)), Name: googlegithub.Ptr("CI")}
steps := workflowJobSteps{{run: run, job: &job}}
frame := steps.Frames()[0]
require.Equal(t, "workflow_job_steps", frame.Name)
require.Equal(t, 3, frame.Rows())
fields := map[string]int{}
for i, field := range frame.Fields {
fields[field.Name] = i
}
require.Equal(t, int64(34), frame.Fields[fields["workflow_id"]].At(0))
require.Equal(t, int64(12), frame.Fields[fields["run_id"]].At(0))
require.Equal(t, int64(2), frame.Fields[fields["run_attempt"]].At(0))
require.Equal(t, "Build (linux)", frame.Fields[fields["job_name"]].At(0))
duration := frame.Fields[fields["duration_seconds"]]
require.Equal(t, "s", duration.Config.Unit)
require.Equal(t, 150.0, *duration.At(0).(*float64))
require.Nil(t, duration.At(1))
require.Nil(t, duration.At(2))
}
12 changes: 12 additions & 0 deletions pkg/github/workflows_handler.go
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,15 @@ func (s *QueryHandler) HandleWorkflowRuns(ctx context.Context, req *backend.Quer
Responses: processQueries(ctx, req, s.handleWorkflowRunsQuery),
}, nil
}

// HandleWorkflowJobSteps handles queries for Actions job step durations.
func (s *QueryHandler) HandleWorkflowJobSteps(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.WorkflowRunsQuery
if err := UnmarshalQuery(q.JSON, &query); err != nil {
return *err
}
return dfutil.FrameResponseWithError(getWorkflowJobSteps(ctx, s.Datasource.client, query.Owner, query.Repository, query.Options.Workflow, query.Options.Branch, q.TimeRange))
})
return &backend.QueryDataResponse{Responses: responses}, nil
}
2 changes: 2 additions & 0 deletions pkg/models/query.go
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ const (
QueryTypeWorkflowUsage QueryType = "Workflow_Usage"
// QueryTypeWorkflowRuns is used when querying workflow runs for a repository
QueryTypeWorkflowRuns QueryType = "Workflow_Runs"
// QueryTypeWorkflowJobSteps is used when querying workflow job step durations.
QueryTypeWorkflowJobSteps QueryType = "Workflow_Job_Steps"
// QueryTypeCodeScanning is used when querying code scanning alerts for a repository
QueryTypeCodeScanning QueryType = "Code_Scanning"
// QueryTypeDeployments is used when querying deployments for a repository
Expand Down
1 change: 1 addition & 0 deletions src/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ export const QueryTypes = [
'Workflows',
'Workflow_Usage',
'Workflow_Runs',
'Workflow_Job_Steps',
'Deployments',
'Webhook_Deliveries',
] as const;
Expand Down
Loading
Loading