From de5d471b2fafe109bdd37439decf1f5ce0a09890 Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 15 May 2025 11:22:34 +0100 Subject: [PATCH 01/17] docs: le vibe --- docs/sources/query/_index.md | 559 +++++++++++++++++++++++++++++++++++ 1 file changed, 559 insertions(+) create mode 100644 docs/sources/query/_index.md diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md new file mode 100644 index 00000000..151df551 --- /dev/null +++ b/docs/sources/query/_index.md @@ -0,0 +1,559 @@ +# GitHub Data Source Plugin Overview + +The GitHub data source plugin for Grafana enables you to query and visualize data directly from your GitHub repositories and organizations. With this plugin, you can monitor repository activity, track issues and pull requests, analyze workflow runs, and more—all within your Grafana dashboards. + +## Query Types + +The plugin supports the following query types: + +- [**Commits**](#commits): Retrieve a list of commits for a repository or branch, including commit messages, authors, and timestamps. +- [**Issues**](#issues): List issues in a repository, with options to filter by state, assignee, and labels. +- [**Contributors**](#contributors): Get a list of contributors to a repository, including their contribution counts. +- [**Tags**](#tags): List tags for a repository, often used to identify release points. +- [**Releases**](#releases): Retrieve information about releases published in a repository. +- [**Pull requests**](#pull-requests): List pull requests for a repository, with filtering by state, author, and labels. +- [**Labels**](#labels): Get all labels defined in a repository, useful for categorizing issues and pull requests. +- [**Repositories**](#repositories): List repositories for a user or organization. +- [**Milestones**](#milestones): Retrieve milestones for a repository, which can be used to group issues and pull requests. +- [**Packages**](#packages): List packages published in a repository or organization. +- [**Vulnerabilities**](#vulnerabilities): Query security vulnerabilities detected in a repository. +- [**Projects**](#projects): List classic projects associated with a repository or organization. +- [**Stargazers**](#stargazers): Get a list of users who have starred a repository. +- [**Workflows**](#workflows): List GitHub Actions workflows defined in a repository. +- [**Workflow usage**](#workflow-usage): Retrieve usage statistics for a workflow, such as run counts and durations. +- [**Workflow runs**](#workflow-runs): List runs for a specific workflow, including status, conclusion, and timing information. + +--- + +## Examples + +### Commits + +Retrieve a list of commits for a repository or branch, including commit messages, authors, and timestamps. Useful for tracking code changes, deployment activity, or contributor history. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. +- **Branch**: (Optional) The branch to filter commits by. +- **Author**: (Optional) Filter commits by a specific author. +- **Since/Until**: (Optional) Filter commits within a date range. + +**Sample query:** +Show all commits to the `main` branch of the `grafana/grafana` repository in the last 7 days. + +- Owner: `grafana` +- Repository: `grafana` +- Branch: `main` +- Since: `2024-05-08` +- Until: `2024-05-15` + +**Sample response:** +```json +[ + { + "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", + "commit": { + "author": { + "name": "Monalisa Octocat", + "email": "octocat@github.com", + "date": "2024-05-10T12:34:56Z" + }, + "message": "Fix all the bugs" + }, + "author": { + "login": "octocat", + "id": 1 + }, + "html_url": "https://github.com/grafana/grafana/commit/7638417db6d59f3c431d3e1f261cc637155684cd" + } +] +``` + +--- + +### Issues + +List issues in a repository, with options to filter by state, assignee, and labels. Useful for tracking open bugs, feature requests, or project tasks. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. +- **State**: Filter by issue state (`open`, `closed`, or `all`). +- **Assignee**: (Optional) Filter by assigned user. +- **Labels**: (Optional) Filter by one or more labels. +- **Creator**: (Optional) Filter by issue creator. +- **Since**: (Optional) Only issues updated at or after this time. + +**Sample query:** +Show all open issues labeled `bug` in the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` +- State: `open` +- Labels: `bug` + +**Sample response:** +```json +[ + { + "id": 1, + "number": 1347, + "title": "Found a bug", + "user": { + "login": "octocat" + }, + "state": "open", + "labels": [ + { + "name": "bug" + } + ], + "created_at": "2024-05-12T09:00:00Z", + "html_url": "https://github.com/grafana/grafana/issues/1347" + } +] +``` + +--- + +### Contributors + +Get a list of contributors to a repository, including their contribution counts. Useful for understanding project activity and top contributors. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all contributors to the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "login": "octocat", + "id": 1, + "contributions": 42 + } +] +``` + +--- + +### Tags + +List tags for a repository, often used to identify release points. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all tags for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "name": "v10.0.0", + "commit": { + "sha": "abc123" + } + } +] +``` + +--- + +### Releases + +Retrieve information about releases published in a repository. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all releases for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "id": 1, + "tag_name": "v10.0.0", + "name": "First Release", + "draft": false, + "prerelease": false, + "created_at": "2024-05-01T00:00:00Z", + "html_url": "https://github.com/grafana/grafana/releases/tag/v10.0.0" + } +] +``` + +--- + +### Pull requests + +List pull requests for a repository, with filtering by state, author, and labels. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. +- **State**: Filter by PR state (`open`, `closed`, or `all`). +- **Author**: (Optional) Filter by author. +- **Labels**: (Optional) Filter by labels. +- **Base**: (Optional) Filter by base branch. + +**Sample query:** +Show all open pull requests authored by `octocat` in the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` +- State: `open` +- Author: `octocat` + +**Sample response:** +```json +[ + { + "id": 2, + "number": 42, + "title": "Add new feature", + "user": { + "login": "octocat" + }, + "state": "open", + "created_at": "2024-05-13T10:00:00Z", + "html_url": "https://github.com/grafana/grafana/pull/42" + } +] +``` + +--- + +### Labels + +Get all labels defined in a repository, useful for categorizing issues and pull requests. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all labels for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "id": 208045946, + "name": "bug", + "color": "f29513" + } +] +``` + +--- + +### Repositories + +List repositories for a user or organization. + +#### Query options + +- **Owner/Organization**: The GitHub user or organization. + +**Sample query:** +Show all repositories for the `grafana` organization. + +- Organization: `grafana` + +**Sample response:** +```json +[ + { + "id": 1296269, + "name": "grafana", + "full_name": "grafana/grafana", + "private": false, + "html_url": "https://github.com/grafana/grafana" + } +] +``` + +--- + +### Milestones + +Retrieve milestones for a repository, which can be used to group issues and pull requests. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. +- **State**: (Optional) Filter by milestone state (`open`, `closed`, or `all`). + +**Sample query:** +Show all open milestones for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` +- State: `open` + +**Sample response:** +```json +[ + { + "id": 1002604, + "number": 1, + "title": "v10.0.0", + "state": "open", + "description": "Release milestone for v10.0.0" + } +] +``` + +--- + +### Packages + +List packages published in a repository or organization. + +#### Query options + +- **Owner/Organization**: The GitHub user or organization. +- **Repository**: (Optional) The name of the repository. + +**Sample query:** +Show all packages for the `grafana` organization. + +- Organization: `grafana` + +**Sample response:** +```json +[ + { + "id": 1, + "name": "grafana-package", + "package_type": "container", + "html_url": "https://github.com/orgs/grafana/packages/container/grafana-package" + } +] +``` + +--- + +### Vulnerabilities + +Query security vulnerabilities detected in a repository. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all security advisories for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "ghsa_id": "GHSA-xxxx-yyyy-zzzz", + "summary": "Vulnerability in dependency", + "severity": "high", + "url": "https://github.com/advisories/GHSA-xxxx-yyyy-zzzz" + } +] +``` + +--- + +### Projects + +List classic projects associated with a repository or organization. + +#### Query options + +- **Owner/Organization**: The GitHub user or organization. +- **Repository**: (Optional) The name of the repository. + +**Sample query:** +Show all projects for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "id": 1002604, + "name": "Roadmap", + "body": "Project roadmap for 2024", + "state": "open" + } +] +``` + +--- + +### Stargazers + +Get a list of users who have starred a repository. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all stargazers for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +[ + { + "starred_at": "2024-05-14T12:00:00Z", + "user": { + "login": "octocat", + "id": 1 + } + } +] +``` + +--- + +### Workflows + +List GitHub Actions workflows defined in a repository. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. + +**Sample query:** +Show all workflows for the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` + +**Sample response:** +```json +{ + "total_count": 2, + "workflows": [ + { + "id": 161335, + "name": "CI", + "path": ".github/workflows/ci.yml", + "state": "active" + } + ] +} +``` + +--- + +### Workflow usage + +Retrieve usage statistics for a workflow, such as run counts and durations. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. +- **Workflow**: The workflow to get usage for. + +**Sample query:** +Show usage statistics for the `CI` workflow in the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` +- Workflow: `CI` + +**Sample response:** +```json +{ + "billable": { + "UBUNTU": { + "total_ms": 1800000, + "jobs": 3, + "runs": 3 + } + } +} +``` + +--- + +### Workflow runs + +List runs for a specific workflow, including status, conclusion, and timing information. + +#### Query options + +- **Owner**: The GitHub user or organization that owns the repository. +- **Repository**: The name of the repository. +- **Workflow**: The workflow to list runs for. +- **Branch**: (Optional) Filter by branch. +- **Status**: (Optional) Filter by status (`queued`, `in_progress`, `completed`). +- **Conclusion**: (Optional) Filter by conclusion (`success`, `failure`, etc.). +- **Created**: (Optional) Filter by creation date. + +**Sample query:** +Show all completed runs for the `CI` workflow on the `main` branch in the `grafana/grafana` repository. + +- Owner: `grafana` +- Repository: `grafana` +- Workflow: `CI` +- Branch: `main` +- Status: `completed` + +**Sample response:** +```json +{ + "total_count": 1, + "workflow_runs": [ + { + "id": 30433642, + "name": "CI", + "head_branch": "main", + "status": "completed", + "conclusion": "success", + "run_number": 562, + "created_at": "2024-05-14T10:00:00Z", + "html_url": "https://github.com/grafana/grafana/actions/runs/30433642" + } + ] +} +``` +--- \ No newline at end of file From 0fc6116048671cf0a609510e62d13c82606f11a6 Mon Sep 17 00:00:00 2001 From: David Harris Date: Thu, 15 May 2025 12:24:09 +0100 Subject: [PATCH 02/17] some corrections --- docs/sources/query/_index.md | 321 +++----------------- docs/sources/variables-and-macros/_index.md | 2 +- 2 files changed, 49 insertions(+), 274 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 151df551..6ade689d 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -1,10 +1,26 @@ -# GitHub Data Source Plugin Overview +--- +title: Query the GitHub data source +menuTitle: Query +description: Learn how to query GitHub using the GitHub data source plugin +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 200 +--- +# Query the GitHub data source -The GitHub data source plugin for Grafana enables you to query and visualize data directly from your GitHub repositories and organizations. With this plugin, you can monitor repository activity, track issues and pull requests, analyze workflow runs, and more—all within your Grafana dashboards. +The GitHub data source plugin for Grafana enables you to query and visualize data directly from your GitHub repositories and organizations. With this plugin, you can monitor repository activity, track issues and pull requests, analyze workflow runs, and more from within Grafana. -## Query Types +## Query types -The plugin supports the following query types: +The data source supports the following queries, which you can select from in the query editor under the `Query Type` dropdown: - [**Commits**](#commits): Retrieve a list of commits for a repository or branch, including commit messages, authors, and timestamps. - [**Issues**](#issues): List issues in a repository, with options to filter by state, assignee, and labels. @@ -35,40 +51,21 @@ Retrieve a list of commits for a repository or branch, including commit messages - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -- **Branch**: (Optional) The branch to filter commits by. -- **Author**: (Optional) Filter commits by a specific author. -- **Since/Until**: (Optional) Filter commits within a date range. +- **Ref (Branch/Tag)**: The branch to filter commits by. -**Sample query:** -Show all commits to the `main` branch of the `grafana/grafana` repository in the last 7 days. +**Sample queries:** +Show all commits to the `main` branch of the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -- Branch: `main` -- Since: `2024-05-08` -- Until: `2024-05-15` - -**Sample response:** -```json -[ - { - "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", - "commit": { - "author": { - "name": "Monalisa Octocat", - "email": "octocat@github.com", - "date": "2024-05-10T12:34:56Z" - }, - "message": "Fix all the bugs" - }, - "author": { - "login": "octocat", - "id": 1 - }, - "html_url": "https://github.com/grafana/grafana/commit/7638417db6d59f3c431d3e1f261cc637155684cd" - } -] -``` +- Ref: `main` + +Show all commits against a tag + +- Owner: `grafana` +- Repository: `grafana` +- Ref: `v12.0.0` + --- @@ -80,42 +77,20 @@ List issues in a repository, with options to filter by state, assignee, and labe - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -- **State**: Filter by issue state (`open`, `closed`, or `all`). -- **Assignee**: (Optional) Filter by assigned user. -- **Labels**: (Optional) Filter by one or more labels. -- **Creator**: (Optional) Filter by issue creator. -- **Since**: (Optional) Only issues updated at or after this time. +- **Query**: A GitHub search query string to filter issues using GitHub's advanced search syntax. This allows you to search by keywords, labels, assignee, author, milestone, state, and more. For details on supported syntax, see [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). +- **Time Field**: The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` -**Sample query:** -Show all open issues labeled `bug` in the `grafana/grafana` repository. +**Sample queries:** +Show all closed issues labeled `type/bug` - Owner: `grafana` - Repository: `grafana` -- State: `open` -- Labels: `bug` - -**Sample response:** -```json -[ - { - "id": 1, - "number": 1347, - "title": "Found a bug", - "user": { - "login": "octocat" - }, - "state": "open", - "labels": [ - { - "name": "bug" - } - ], - "created_at": "2024-05-12T09:00:00Z", - "html_url": "https://github.com/grafana/grafana/issues/1347" - } -] -``` +- Query: `is:closed label:type/bug` +Show all issues with 'sql expressions' in the title +- Owner: `grafana` +- Repository: `grafana` +- Query: `sql expressions in:title` --- ### Contributors @@ -126,23 +101,20 @@ Get a list of contributors to a repository, including their contribution counts. - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. +- **Query (optional)**: Filter for contributors by name or GitHub handle -**Sample query:** +**Sample queries:** Show all contributors to the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "login": "octocat", - "id": 1, - "contributions": 42 - } -] -``` +Search for contributors with `bob` in their name or handle + +- Owner: `grafana` +- Repository: `grafana` +- Query: `bob` + --- @@ -161,18 +133,6 @@ Show all tags for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "name": "v10.0.0", - "commit": { - "sha": "abc123" - } - } -] -``` - --- ### Releases @@ -190,21 +150,6 @@ Show all releases for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "id": 1, - "tag_name": "v10.0.0", - "name": "First Release", - "draft": false, - "prerelease": false, - "created_at": "2024-05-01T00:00:00Z", - "html_url": "https://github.com/grafana/grafana/releases/tag/v10.0.0" - } -] -``` - --- ### Pull requests @@ -228,25 +173,6 @@ Show all open pull requests authored by `octocat` in the `grafana/grafana` repos - State: `open` - Author: `octocat` -**Sample response:** -```json -[ - { - "id": 2, - "number": 42, - "title": "Add new feature", - "user": { - "login": "octocat" - }, - "state": "open", - "created_at": "2024-05-13T10:00:00Z", - "html_url": "https://github.com/grafana/grafana/pull/42" - } -] -``` - ---- - ### Labels Get all labels defined in a repository, useful for categorizing issues and pull requests. @@ -262,19 +188,6 @@ Show all labels for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "id": 208045946, - "name": "bug", - "color": "f29513" - } -] -``` - ---- - ### Repositories List repositories for a user or organization. @@ -288,21 +201,6 @@ Show all repositories for the `grafana` organization. - Organization: `grafana` -**Sample response:** -```json -[ - { - "id": 1296269, - "name": "grafana", - "full_name": "grafana/grafana", - "private": false, - "html_url": "https://github.com/grafana/grafana" - } -] -``` - ---- - ### Milestones Retrieve milestones for a repository, which can be used to group issues and pull requests. @@ -320,21 +218,6 @@ Show all open milestones for the `grafana/grafana` repository. - Repository: `grafana` - State: `open` -**Sample response:** -```json -[ - { - "id": 1002604, - "number": 1, - "title": "v10.0.0", - "state": "open", - "description": "Release milestone for v10.0.0" - } -] -``` - ---- - ### Packages List packages published in a repository or organization. @@ -349,20 +232,6 @@ Show all packages for the `grafana` organization. - Organization: `grafana` -**Sample response:** -```json -[ - { - "id": 1, - "name": "grafana-package", - "package_type": "container", - "html_url": "https://github.com/orgs/grafana/packages/container/grafana-package" - } -] -``` - ---- - ### Vulnerabilities Query security vulnerabilities detected in a repository. @@ -378,20 +247,6 @@ Show all security advisories for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "ghsa_id": "GHSA-xxxx-yyyy-zzzz", - "summary": "Vulnerability in dependency", - "severity": "high", - "url": "https://github.com/advisories/GHSA-xxxx-yyyy-zzzz" - } -] -``` - ---- - ### Projects List classic projects associated with a repository or organization. @@ -407,20 +262,6 @@ Show all projects for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "id": 1002604, - "name": "Roadmap", - "body": "Project roadmap for 2024", - "state": "open" - } -] -``` - ---- - ### Stargazers Get a list of users who have starred a repository. @@ -436,21 +277,6 @@ Show all stargazers for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -[ - { - "starred_at": "2024-05-14T12:00:00Z", - "user": { - "login": "octocat", - "id": 1 - } - } -] -``` - ---- - ### Workflows List GitHub Actions workflows defined in a repository. @@ -466,23 +292,6 @@ Show all workflows for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -**Sample response:** -```json -{ - "total_count": 2, - "workflows": [ - { - "id": 161335, - "name": "CI", - "path": ".github/workflows/ci.yml", - "state": "active" - } - ] -} -``` - ---- - ### Workflow usage Retrieve usage statistics for a workflow, such as run counts and durations. @@ -500,20 +309,6 @@ Show usage statistics for the `CI` workflow in the `grafana/grafana` repository. - Repository: `grafana` - Workflow: `CI` -**Sample response:** -```json -{ - "billable": { - "UBUNTU": { - "total_ms": 1800000, - "jobs": 3, - "runs": 3 - } - } -} -``` - ---- ### Workflow runs @@ -537,23 +332,3 @@ Show all completed runs for the `CI` workflow on the `main` branch in the `grafa - Workflow: `CI` - Branch: `main` - Status: `completed` - -**Sample response:** -```json -{ - "total_count": 1, - "workflow_runs": [ - { - "id": 30433642, - "name": "CI", - "head_branch": "main", - "status": "completed", - "conclusion": "success", - "run_number": 562, - "created_at": "2024-05-14T10:00:00Z", - "html_url": "https://github.com/grafana/grafana/actions/runs/30433642" - } - ] -} -``` ---- \ No newline at end of file diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index edc33ee2..774a0b5d 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -12,7 +12,7 @@ labels: - oss - enterprise - cloud -weight: 200 +weight: 300 --- # Use GitHub data source variables and macros in Grafana From 5515ecf3d79049f963254453f2ff4ef6549eea15 Mon Sep 17 00:00:00 2001 From: David Harris Date: Sun, 18 May 2025 14:19:55 +0100 Subject: [PATCH 03/17] wip --- docs/sources/query/_index.md | 131 +++++++++++++++++++++++++---------- 1 file changed, 94 insertions(+), 37 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 6ade689d..1ba87945 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -22,13 +22,13 @@ The GitHub data source plugin for Grafana enables you to query and visualize dat The data source supports the following queries, which you can select from in the query editor under the `Query Type` dropdown: -- [**Commits**](#commits): Retrieve a list of commits for a repository or branch, including commit messages, authors, and timestamps. -- [**Issues**](#issues): List issues in a repository, with options to filter by state, assignee, and labels. -- [**Contributors**](#contributors): Get a list of contributors to a repository, including their contribution counts. -- [**Tags**](#tags): List tags for a repository, often used to identify release points. -- [**Releases**](#releases): Retrieve information about releases published in a repository. -- [**Pull requests**](#pull-requests): List pull requests for a repository, with filtering by state, author, and labels. -- [**Labels**](#labels): Get all labels defined in a repository, useful for categorizing issues and pull requests. +- [**Commits**](#commits): Retrieve a list of commits for a repository or branch, including commit message, author, and timestamp. +- [**Issues**](#issues): List issues in a repository, using the GitHub query syntax to filter the response. +- [**Contributors**](#contributors): Get a list of contributors to a repository. +- [**Tags**](#tags): List created tags for a repository. +- [**Releases**](#releases): List created releases for a repository. +- [**Pull requests**](#pull-requests): List pull requests for a repository, using the GitHub query syntax to filter the response. +- [**Labels**](#labels): List labels defined in a repository. - [**Repositories**](#repositories): List repositories for a user or organization. - [**Milestones**](#milestones): Retrieve milestones for a repository, which can be used to group issues and pull requests. - [**Packages**](#packages): List packages published in a repository or organization. @@ -39,19 +39,16 @@ The data source supports the following queries, which you can select from in the - [**Workflow usage**](#workflow-usage): Retrieve usage statistics for a workflow, such as run counts and durations. - [**Workflow runs**](#workflow-runs): List runs for a specific workflow, including status, conclusion, and timing information. ---- - -## Examples - ### Commits Retrieve a list of commits for a repository or branch, including commit messages, authors, and timestamps. Useful for tracking code changes, deployment activity, or contributor history. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **Ref (Branch/Tag)**: The branch to filter commits by. +| Name | Description | Required (yes/no) | +| Owner | The GitHub user or organization that owns the repository. | Yes | +| Repository | The name of the repository | Yes | +| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | **Sample queries:** Show all commits to the `main` branch of the `grafana/grafana` repository. @@ -66,22 +63,35 @@ Show all commits against a tag - Repository: `grafana` - Ref: `v12.0.0` +#### Response ---- +| Name | Description | +| id | commit ID | +| author | Name of the commit author | +| author_login | GitHub handle of the commit author | +| author_company | Company name of the commit author | +| committed_at | YYYY-MM-DD HH:MM:SS | +| pushed_at | YYYY-MM-DD HH:MM:SS | +| message | commit message | ### Issues -List issues in a repository, with options to filter by state, assignee, and labels. Useful for tracking open bugs, feature requests, or project tasks. +List issues in a repository using the GitHub query syntax to filter the response. Useful for tracking open bugs, feature requests, or project tasks. #### Query options +| Name | Description | Required (yes/no) | +| Owner | The GitHub user or organization that owns the repository. | Yes | +| Repository | The name of the repository | Yes | +| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | + - **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **Query**: A GitHub search query string to filter issues using GitHub's advanced search syntax. This allows you to search by keywords, labels, assignee, author, milestone, state, and more. For details on supported syntax, see [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). +- **Repository**: (Optional) The name of the repository. +- **Query**: (Optional) A GitHub search query string to filter issues using GitHub's advanced search syntax. This allows you to search by keywords, labels, assignee, author, milestone, state, and more. For details on supported syntax, see [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). - **Time Field**: The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` **Sample queries:** -Show all closed issues labeled `type/bug` +Show all closed issues labeled `type/bug` in the grafana repository. - Owner: `grafana` - Repository: `grafana` @@ -91,11 +101,26 @@ Show all issues with 'sql expressions' in the title - Owner: `grafana` - Repository: `grafana` - Query: `sql expressions in:title` ---- + +#### Response + +| Name | Description | +| title | Issue title | +| author | GitHub handle of the author | +| author_company | Company name of the commit author | +| repo | Issue repository | +| number | Issue number | +| closed | true / false | +| created_at | YYYY-MM-DD HH:MM:SS | +| closed_at | YYYY-MM-DD HH:MM:SS | +| updated_at | YYYY-MM-DD HH:MM:SS | +| labels | Array of labels i.e. [ "type/bug", "needs more info"] | + +Note: This query returns a maximum of 1000 results. ### Contributors -Get a list of contributors to a repository, including their contribution counts. Useful for understanding project activity and top contributors. +Get a list of contributors to a repository. #### Query options @@ -104,7 +129,7 @@ Get a list of contributors to a repository, including their contribution counts. - **Query (optional)**: Filter for contributors by name or GitHub handle **Sample queries:** -Show all contributors to the `grafana/grafana` repository. +Show all contributors to the `grafana` repository. - Owner: `grafana` - Repository: `grafana` @@ -115,12 +140,22 @@ Search for contributors with `bob` in their name or handle - Repository: `grafana` - Query: `bob` +#### Response ---- +| Name | Description | +| Name | Name of the contributor | +| author | Name of the commit author | +| author_login | GitHub handle of the commit author | +| author_company | Company name of the commit author | +| committed_at | YYYY-MM-DD HH:MM:SS | +| pushed_at | YYYY-MM-DD HH:MM:SS | +| message | commit message | + +Note: This query returns a maximum of 200 results. ### Tags -List tags for a repository, often used to identify release points. +List created tags for a repository. #### Query options @@ -128,16 +163,24 @@ List tags for a repository, often used to identify release points. - **Repository**: The name of the repository. **Sample query:** -Show all tags for the `grafana/grafana` repository. +Show all tags created for the `grafana` repository within the current selected time range. - Owner: `grafana` - Repository: `grafana` ---- +#### Response + +| Name | Description | +| Name | Name of tag | +| id | Sha for the tag| +| author | Name of the GitHub user who created the tag | +| author_login | GitHub handle of the GitHub user who created the tag | +| author_company | Company name of the GitHub user who created the tag | +| date | YYYY-MM-DD HH:MM:SS | ### Releases -Retrieve information about releases published in a repository. +List created releases for a repository. #### Query options @@ -148,28 +191,35 @@ Retrieve information about releases published in a repository. Show all releases for the `grafana/grafana` repository. - Owner: `grafana` -- Repository: `grafana` +- Repository : `grafana` ---- +#### Response + +| Name | Description | +| Name | Name of release | +| created_by | Name of the GitHub user who created the release | +| is_draft | true / false| +| is_prerelease | true / false| +| tag | Tag name associated with the release | +| url | URL for the tag associated with the release | +| created_at | YYYY-MM-DD HH:MM:SS | +| published_at | YYYY-MM-DD HH:MM:SS | ### Pull requests -List pull requests for a repository, with filtering by state, author, and labels. +List pull requests for a repository, using the GitHub query syntax to filter the response. #### Query options - **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **State**: Filter by PR state (`open`, `closed`, or `all`). -- **Author**: (Optional) Filter by author. -- **Labels**: (Optional) Filter by labels. -- **Base**: (Optional) Filter by base branch. +- **Repository**: (Optional) The name of the repository. + **Sample query:** Show all open pull requests authored by `octocat` in the `grafana/grafana` repository. -- Owner: `grafana` -- Repository: `grafana` +- Owner : `grafana` +- Repository : `grafana` - State: `open` - Author: `octocat` @@ -188,6 +238,13 @@ Show all labels for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` +#### Response + +| Name | Description | +| color | Hexadecimal number | +| name | Label name | +| description | Label description | + ### Repositories List repositories for a user or organization. From 9c9da5c64a6338e11bad8c99d23a20c1200459a1 Mon Sep 17 00:00:00 2001 From: David Harris Date: Sun, 18 May 2025 17:32:14 +0100 Subject: [PATCH 04/17] wip --- docs/sources/query/_index.md | 55 ++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 21 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 1ba87945..2a38338b 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -46,11 +46,12 @@ Retrieve a list of commits for a repository or branch, including commit messages #### Query options | Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | | Owner | The GitHub user or organization that owns the repository. | Yes | | Repository | The name of the repository | Yes | | Ref (Branch/Tag) | The branch or tag to list commits against | Yes | -**Sample queries:** +##### Sample queries Show all commits to the `main` branch of the `grafana/grafana` repository. - Owner: `grafana` @@ -66,6 +67,7 @@ Show all commits against a tag #### Response | Name | Description | +| ---- | ----------- | | id | commit ID | | author | Name of the commit author | | author_login | GitHub handle of the commit author | @@ -81,6 +83,7 @@ List issues in a repository using the GitHub query syntax to filter the response #### Query options | Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | | Owner | The GitHub user or organization that owns the repository. | Yes | | Repository | The name of the repository | Yes | | Ref (Branch/Tag) | The branch or tag to list commits against | Yes | @@ -90,7 +93,7 @@ List issues in a repository using the GitHub query syntax to filter the response - **Query**: (Optional) A GitHub search query string to filter issues using GitHub's advanced search syntax. This allows you to search by keywords, labels, assignee, author, milestone, state, and more. For details on supported syntax, see [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). - **Time Field**: The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` -**Sample queries:** +##### Sample queries Show all closed issues labeled `type/bug` in the grafana repository. - Owner: `grafana` @@ -105,6 +108,7 @@ Show all issues with 'sql expressions' in the title #### Response | Name | Description | +| ---- | ----------- | | title | Issue title | | author | GitHub handle of the author | | author_company | Company name of the commit author | @@ -116,7 +120,9 @@ Show all issues with 'sql expressions' in the title | updated_at | YYYY-MM-DD HH:MM:SS | | labels | Array of labels i.e. [ "type/bug", "needs more info"] | -Note: This query returns a maximum of 1000 results. +{{< admonition type="note" >}} +This query returns a maximum of 1000 results. +{{< /admonition >}} ### Contributors @@ -124,11 +130,13 @@ Get a list of contributors to a repository. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **Query (optional)**: Filter for contributors by name or GitHub handle +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository. | Yes | +| Repository | The name of the repository. | | +| Query | Filter for contributors by name or GitHub handle | No | -**Sample queries:** +##### Sample queries Show all contributors to the `grafana` repository. - Owner: `grafana` @@ -143,6 +151,7 @@ Search for contributors with `bob` in their name or handle #### Response | Name | Description | +| ---- | ----------- | | Name | Name of the contributor | | author | Name of the commit author | | author_login | GitHub handle of the commit author | @@ -151,7 +160,9 @@ Search for contributors with `bob` in their name or handle | pushed_at | YYYY-MM-DD HH:MM:SS | | message | commit message | -Note: This query returns a maximum of 200 results. +{{< admonition type="note" >}} +This query returns a maximum of 200 results. +{{< /admonition >}} ### Tags @@ -162,7 +173,7 @@ List created tags for a repository. - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -**Sample query:** +##### Sample queries Show all tags created for the `grafana` repository within the current selected time range. - Owner: `grafana` @@ -171,6 +182,7 @@ Show all tags created for the `grafana` repository within the current selected t #### Response | Name | Description | +| ---- | ----------- | | Name | Name of tag | | id | Sha for the tag| | author | Name of the GitHub user who created the tag | @@ -187,7 +199,7 @@ List created releases for a repository. - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -**Sample query:** +##### Sample queries Show all releases for the `grafana/grafana` repository. - Owner: `grafana` @@ -196,6 +208,7 @@ Show all releases for the `grafana/grafana` repository. #### Response | Name | Description | +| ---- | ----------- | | Name | Name of release | | created_by | Name of the GitHub user who created the release | | is_draft | true / false| @@ -215,7 +228,7 @@ List pull requests for a repository, using the GitHub query syntax to filter the - **Repository**: (Optional) The name of the repository. -**Sample query:** +##### Sample queries Show all open pull requests authored by `octocat` in the `grafana/grafana` repository. - Owner : `grafana` @@ -232,7 +245,7 @@ Get all labels defined in a repository, useful for categorizing issues and pull - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -**Sample query:** +##### Sample queries Show all labels for the `grafana/grafana` repository. - Owner: `grafana` @@ -253,7 +266,7 @@ List repositories for a user or organization. - **Owner/Organization**: The GitHub user or organization. -**Sample query:** +##### Sample queries Show all repositories for the `grafana` organization. - Organization: `grafana` @@ -268,7 +281,7 @@ Retrieve milestones for a repository, which can be used to group issues and pull - **Repository**: The name of the repository. - **State**: (Optional) Filter by milestone state (`open`, `closed`, or `all`). -**Sample query:** +##### Sample queries Show all open milestones for the `grafana/grafana` repository. - Owner: `grafana` @@ -284,7 +297,7 @@ List packages published in a repository or organization. - **Owner/Organization**: The GitHub user or organization. - **Repository**: (Optional) The name of the repository. -**Sample query:** +##### Sample queries Show all packages for the `grafana` organization. - Organization: `grafana` @@ -298,7 +311,7 @@ Query security vulnerabilities detected in a repository. - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -**Sample query:** +##### Sample queries Show all security advisories for the `grafana/grafana` repository. - Owner: `grafana` @@ -313,7 +326,7 @@ List classic projects associated with a repository or organization. - **Owner/Organization**: The GitHub user or organization. - **Repository**: (Optional) The name of the repository. -**Sample query:** +##### Sample queries Show all projects for the `grafana/grafana` repository. - Owner: `grafana` @@ -328,7 +341,7 @@ Get a list of users who have starred a repository. - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -**Sample query:** +##### Sample queries Show all stargazers for the `grafana/grafana` repository. - Owner: `grafana` @@ -343,7 +356,7 @@ List GitHub Actions workflows defined in a repository. - **Owner**: The GitHub user or organization that owns the repository. - **Repository**: The name of the repository. -**Sample query:** +##### Sample queries Show all workflows for the `grafana/grafana` repository. - Owner: `grafana` @@ -359,7 +372,7 @@ Retrieve usage statistics for a workflow, such as run counts and durations. - **Repository**: The name of the repository. - **Workflow**: The workflow to get usage for. -**Sample query:** +##### Sample queries Show usage statistics for the `CI` workflow in the `grafana/grafana` repository. - Owner: `grafana` @@ -381,7 +394,7 @@ List runs for a specific workflow, including status, conclusion, and timing info - **Conclusion**: (Optional) Filter by conclusion (`success`, `failure`, etc.). - **Created**: (Optional) Filter by creation date. -**Sample query:** +##### Sample queries Show all completed runs for the `CI` workflow on the `main` branch in the `grafana/grafana` repository. - Owner: `grafana` From 9e9f86cbc3be1e28ffeece8582e40d1661b1d08b Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 19 May 2025 13:07:14 +0100 Subject: [PATCH 05/17] wip --- docs/sources/query/_index.md | 60 ++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 16 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 2a38338b..64f1f986 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -84,14 +84,10 @@ List issues in a repository using the GitHub query syntax to filter the response | Name | Description | Required (yes/no) | | ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository. | Yes | -| Repository | The name of the repository | Yes | -| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | - -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: (Optional) The name of the repository. -- **Query**: (Optional) A GitHub search query string to filter issues using GitHub's advanced search syntax. This allows you to search by keywords, labels, assignee, author, milestone, state, and more. For details on supported syntax, see [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). -- **Time Field**: The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` +| Owner | A GitHub user or organization | Yes | +| Repository | The name of a repository | No | +| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | +| Time field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` | ##### Sample queries Show all closed issues labeled `type/bug` in the grafana repository. @@ -126,14 +122,14 @@ This query returns a maximum of 1000 results. ### Contributors -Get a list of contributors to a repository. +Get a list of contributors to an organization or repository. #### Query options | Name | Description | Required (yes/no) | | ---- | ----------- | ----------------- | | Owner | The GitHub user or organization that owns the repository. | Yes | -| Repository | The name of the repository. | | +| Repository | The name of a repository. | No | | Query | Filter for contributors by name or GitHub handle | No | ##### Sample queries @@ -170,8 +166,10 @@ List created tags for a repository. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository. | Yes | ##### Sample queries Show all tags created for the `grafana` repository within the current selected time range. @@ -196,8 +194,10 @@ List created releases for a repository. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository. | Yes | ##### Sample queries Show all releases for the `grafana/grafana` repository. @@ -224,8 +224,12 @@ List pull requests for a repository, using the GitHub query syntax to filter the #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: (Optional) The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | No | +| Query | | No | +| Time field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt`, `UpdatedAt` or `none` | ##### Sample queries @@ -236,6 +240,30 @@ Show all open pull requests authored by `octocat` in the `grafana/grafana` repos - State: `open` - Author: `octocat` +#### Response +| Name | Description | +| ---- | ----------- | +| Number | Pull request number | +| Title | Pull request title | +| URL | URL to the pull request | +| Additions | Total number of lines of code that have been added or altered in the pull request | +| Deletions | Total number of lines of code that have been removed or altered in the pull request | +| Repository | Repository for the pull request | +| State | Can be `open`, `closed` or `merged` | +| author_name | Name of the GitHub user who created the pull request | +| author_login | GitHub handle of the GitHub user who created the pull request | +| author_email | Email address of the GitHub user who created the pull request | +| author_company | Company name of the GitHub user who created the pull request | +| closed | Whether the pull request is closed: `true` / `false` | +| is_draft | Whether the pull request is in draft: `true` / `false` | +| locked | Whether the pull request has been locked: `true` / `false` | +| merged | Whether the pull request has been merged | +| mergeable | Whether the pull request can be automatically merged: `MERGEABLE`, `CONFLICTING` or `UNKNOWN` | +| closed_at | When the pull request was closed: YYYY-MM-DD HH:MM:SS | +| merged_at | When the pull request was merged: YYYY-MM-DD HH:MM:SS | +| merged_by_name | Name of the GitHub user who merged the pull request | +| merged_by_login | GitHub handle of the GitHub user who merged the pull request | + ### Labels Get all labels defined in a repository, useful for categorizing issues and pull requests. From 3b80fd2747d3454989b0ed3405e5796efa866dfe Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 19 May 2025 13:22:59 +0100 Subject: [PATCH 06/17] wip --- docs/sources/query/_index.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 64f1f986..6e073d09 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -233,12 +233,12 @@ List pull requests for a repository, using the GitHub query syntax to filter the ##### Sample queries -Show all open pull requests authored by `octocat` in the `grafana/grafana` repository. +Show all open pull requests authored by renovate in the `grafana/plugin-tools` repository. - Owner : `grafana` - Repository : `grafana` -- State: `open` -- Author: `octocat` +- Query: `is:open author:app/renovate` +- Time field: `none` #### Response | Name | Description | @@ -270,8 +270,11 @@ Get all labels defined in a repository, useful for categorizing issues and pull #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter on text in name and description for labels | No | ##### Sample queries Show all labels for the `grafana/grafana` repository. @@ -281,6 +284,8 @@ Show all labels for the `grafana/grafana` repository. #### Response +| Name | Description | +| ---- | ----------- | | Name | Description | | color | Hexadecimal number | | name | Label name | @@ -292,13 +297,32 @@ List repositories for a user or organization. #### Query options -- **Owner/Organization**: The GitHub user or organization. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository - can be used for getting details on a single repository | No | ##### Sample queries Show all repositories for the `grafana` organization. - Organization: `grafana` +#### Response + +| Name | Description | +| ---- | ----------- | +| Name | Name of the repository | +| Owner | Organization or user who owns the repository | +| Name_with_owner| Returns the owner and repository name in the format / i.e. `grafana/loki` | +| Url | URL for the repository | +| Forks | The number of forks for a repository | +| Is_mirror | Whether the repository is a mirror of another repository: `true` / `false` | + + +{{< admonition type="note" >}} +This query returns a maximum of 1000 results. +{{< /admonition >}} + ### Milestones Retrieve milestones for a repository, which can be used to group issues and pull requests. From 134e19f5eebd19839fa5102a505eb4c56b134fc6 Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 19 May 2025 13:29:39 +0100 Subject: [PATCH 07/17] wip - next up milestones --- docs/sources/query/_index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 6e073d09..a0c4466c 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -317,6 +317,8 @@ Show all repositories for the `grafana` organization. | Url | URL for the repository | | Forks | The number of forks for a repository | | Is_mirror | Whether the repository is a mirror of another repository: `true` / `false` | +| is_private | Whether the repository is private: `true` / `false` | +| created_at | When the repository was created: YYYY-MM-DD HH:MM:SS | {{< admonition type="note" >}} From 9e4d463ec9430a4d0b649c56c20fa36704eb72a7 Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 19 May 2025 14:13:17 +0100 Subject: [PATCH 08/17] update response values to be lower case --- docs/sources/query/_index.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index a0c4466c..9efa70cc 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -148,7 +148,7 @@ Search for contributors with `bob` in their name or handle | Name | Description | | ---- | ----------- | -| Name | Name of the contributor | +| name | Name of the contributor | | author | Name of the commit author | | author_login | GitHub handle of the commit author | | author_company | Company name of the commit author | @@ -181,7 +181,7 @@ Show all tags created for the `grafana` repository within the current selected t | Name | Description | | ---- | ----------- | -| Name | Name of tag | +| name | Name of tag | | id | Sha for the tag| | author | Name of the GitHub user who created the tag | | author_login | GitHub handle of the GitHub user who created the tag | @@ -209,7 +209,7 @@ Show all releases for the `grafana/grafana` repository. | Name | Description | | ---- | ----------- | -| Name | Name of release | +| name | Name of release | | created_by | Name of the GitHub user who created the release | | is_draft | true / false| | is_prerelease | true / false| @@ -243,13 +243,13 @@ Show all open pull requests authored by renovate in the `grafana/plugin-tools` r #### Response | Name | Description | | ---- | ----------- | -| Number | Pull request number | -| Title | Pull request title | -| URL | URL to the pull request | -| Additions | Total number of lines of code that have been added or altered in the pull request | -| Deletions | Total number of lines of code that have been removed or altered in the pull request | -| Repository | Repository for the pull request | -| State | Can be `open`, `closed` or `merged` | +| number | Pull request number | +| title | Pull request title | +| url | URL to the pull request | +| additions | Total number of lines of code that have been added or altered in the pull request | +| deletions | Total number of lines of code that have been removed or altered in the pull request | +| repository | Repository for the pull request | +| state | Can be `open`, `closed` or `merged` | | author_name | Name of the GitHub user who created the pull request | | author_login | GitHub handle of the GitHub user who created the pull request | | author_email | Email address of the GitHub user who created the pull request | From 6b85300204aae3d2c4d8b47f46b8a541bea45129 Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 19 May 2025 22:36:22 +0100 Subject: [PATCH 09/17] wip - up to stargazers --- docs/sources/query/_index.md | 158 +++++++++++++++++++++++++++++++---- 1 file changed, 140 insertions(+), 18 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 9efa70cc..428f4a1b 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -31,9 +31,9 @@ The data source supports the following queries, which you can select from in the - [**Labels**](#labels): List labels defined in a repository. - [**Repositories**](#repositories): List repositories for a user or organization. - [**Milestones**](#milestones): Retrieve milestones for a repository, which can be used to group issues and pull requests. -- [**Packages**](#packages): List packages published in a repository or organization. +- [**Packages**](#packages): List packages published from a repository in an organization. - [**Vulnerabilities**](#vulnerabilities): Query security vulnerabilities detected in a repository. -- [**Projects**](#projects): List classic projects associated with a repository or organization. +- [**Projects**](#projects): List projects associated with a user or organization. - [**Stargazers**](#stargazers): Get a list of users who have starred a repository. - [**Workflows**](#workflows): List GitHub Actions workflows defined in a repository. - [**Workflow usage**](#workflow-usage): Retrieve usage statistics for a workflow, such as run counts and durations. @@ -331,39 +331,84 @@ Retrieve milestones for a repository, which can be used to group issues and pull #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **State**: (Optional) Filter by milestone state (`open`, `closed`, or `all`). +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter on text in the milestone title | No | ##### Sample queries -Show all open milestones for the `grafana/grafana` repository. +Show all milestones for the `grafana/grafana` repository for v11 of Grafana - Owner: `grafana` - Repository: `grafana` -- State: `open` +- Query: `11.` + +#### Response + +| Name | Description | +| ---- | ----------- | +| title | Milestone title | +| author | GitHub handle of the user who created the milestone | +| closed | Whether the milestone is closed: `true` / `false` | +| state | One of `OPEN` or `CLOSED` | +| created_at | When the milestone was created: YYYY-MM-DD HH:MM:SS | +| closed_at | When the milestone was closed: YYYY-MM-DD HH:MM:SS | +| due_at | When the milestone is due by: YYYY-MM-DD HH:MM:SS | + +{{< admonition type="note" >}} +Milestone titles can be anything and are therefore parsed as a string. +This means sorting by title may appear incorrect if you have numeric milestones i.e. `12.0.0`. +[Transformations](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/) +can be used to change the data type in this scenario. +{{< /admonition >}} ### Packages -List packages published in a repository or organization. +List packages published from a repository in an organization #### Query options -- **Owner/Organization**: The GitHub user or organization. -- **Repository**: (Optional) The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Package type | One of: `MAVEN`, `DOCKER`, `DEBIAN` or `PYPI` | Yes | +| Names | Filter for packages using a comma separated list of names | No | + ##### Sample queries -Show all packages for the `grafana` organization. +Show all packages uploaded t the `grafana` organization. - Organization: `grafana` +#### Response + +| Name | Description | +| ---- | ----------- | +| name | Package name | +| platform | Platform or registry where the package is published | +| version | Package version | +| type | Package type (e.g., MAVEN, DOCKER, DEBIAN, PYPI) | +| prerelease | Whether the package version is a prerelease: `true` / `false` | +| downloads | Number of downloads for the package version | + +{{< admonition type="note" >}} +This query does not support querying npm, RubyGems or NuGet packages. +{{< /admonition >}} + ### Vulnerabilities Query security vulnerabilities detected in a repository. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | + + ##### Sample queries Show all security advisories for the `grafana/grafana` repository. @@ -371,20 +416,97 @@ Show all security advisories for the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` + When the vulnerability was : YYYY-MM-DD HH:MM:SS + +#### Response + +| Name | Description | +|------------------------|-------------| +| value | Custom field which allows for counting or aggregation, always returns `1` | +| created_at | When the vulnerability alert was created (when the vulnerability was published on GitHub): YYYY-MM-DD HH:MM:SS | +| dismissed_at | When the vulnerability alert was dismissed, if applicable: YYYY-MM-DD HH:MM:SS | +| dismissed_reason | Reason the vulnerability alert was dismissed (e.g., false positive, won't fix), if applicable | +| withdrawn_at | When the advisory was withdrawn, if applicable: YYYY-MM-DD HH:MM:SS | +| packageName | Name of the affected package | +| advisoryDescription | Description of the vulnerability/advisory | +| firstPatchedVersion | The first version of the package where the vulnerability is fixed | +| vulnerableVersionRange | The range of package versions affected by the vulnerability | +| cvssScore | CVSS (Common Vulnerability Scoring System) score for the vulnerability | +| cvssVector | CVSS vector string describing the scoring metrics | +| permalink | URL to the GitHub Security Advisory or alert | +| severity | Severity level of the vulnerability (e.g., LOW, MODERATE, HIGH, CRITICAL) | +| state | State of the vulnerability alert (e.g., OPEN, FIXED, DISMISSED) | + ### Projects -List classic projects associated with a repository or organization. +List projects associated with a user or organization. #### Query options -- **Owner/Organization**: The GitHub user or organization. -- **Repository**: (Optional) The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Project Owner | One of `Organization` or `User` | Yes | +| Organization | Organization for the Project (shown when Organization was previously selected) | Yes | +| User | User for the Project (shown when User was previously selected) | Yes | +| Project Number | Enter a specific Project Number to query for associated items | No | +| Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | ##### Sample queries Show all projects for the `grafana/grafana` repository. -- Owner: `grafana` -- Repository: `grafana` +- Project Owner: `organization` +- Organization: `grafana` + +Show all pull requests for the "Dashboards" project in the Grafana organization + +- Project Owner: `organization` +- Organization: `grafana` +- Project Number: `202` +- Filter: `type equal PULL_REQUEST` + +#### Response + +##### When no Project Number is specified + +| Name | Description | +|--------------|-------------| +| number| The project number | +| title | Title of the project | +| url | URL for the project | +| closed | Whether the project has been closed: `true`/ `false` | +| public | Whether the project is public: `true` / `false | +| closed_at | When the project was closed: YYYY-MM-DD HH:MM:SS | +| updated_at | When the project was last updated | +| created_at | When the project was created | +| short_description | The description of the project | + +{{< admonition type="note" >}} +This query returns a maximum of 200 results. +{{< /admonition >}} + +##### When a Project Number is specified +{{< admonition type="note" >}} +GitHub Projects allow for customization of default fields and custom fields to be added, +therefore the response can vary significantly between projects." +{{< /admonition >}} + +| Name | Description | +|--------------|-------------| +| name | Name of the project item (issue or pull request) | +| id | Unique identifier for the project item | +| type | Type of the item (e.g., ISSUE, PULL_REQUEST) | +| status | Status of the item (e.g., "In development", "Shipped") - this can be configured on the project | +| labels | Comma-separated list of labels assigned to the item | +| assignees | Comma-separated list of users assigned to the item | +| reviewers | Comma-separated list of reviewers (for pull requests) | +| repository | Name of the repository the item belongs to | +| milestone | Milestone associated with the item | +| priority | Priority value or label | +| archived | Whether the item is archived: `true` / `false` | +| created_at | When the item was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the item was last updated: YYYY-MM-DD HH:MM:SS | +| closed_at | When the item was closed, if applicable: YYYY-MM-DD HH:MM:SS | +| (custom fields) | Any custom defined fields will also be returned alongside their values | ### Stargazers From 9d7fbcff0c24088b6addab513b71c7b4c1ea3a3a Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 20 May 2025 09:51:46 +0100 Subject: [PATCH 10/17] wip wrap up draft content --- docs/sources/query/_index.md | 124 ++++++++++++++++++++++++++++------- 1 file changed, 100 insertions(+), 24 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 428f4a1b..d7fb80c2 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -34,7 +34,7 @@ The data source supports the following queries, which you can select from in the - [**Packages**](#packages): List packages published from a repository in an organization. - [**Vulnerabilities**](#vulnerabilities): Query security vulnerabilities detected in a repository. - [**Projects**](#projects): List projects associated with a user or organization. -- [**Stargazers**](#stargazers): Get a list of users who have starred a repository. +- [**Stargazers**](#stargazers): Get a list of users who have starred a repository, including being able to plot a total count over time. - [**Workflows**](#workflows): List GitHub Actions workflows defined in a repository. - [**Workflow usage**](#workflow-usage): Retrieve usage statistics for a workflow, such as run counts and durations. - [**Workflow runs**](#workflow-runs): List runs for a specific workflow, including status, conclusion, and timing information. @@ -510,33 +510,68 @@ therefore the response can vary significantly between projects." ### Stargazers -Get a list of users who have starred a repository. +Get a list of users who have starred a repository, including being able to plot a total count over time #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries -Show all stargazers for the `grafana/grafana` repository. +Show all stargazers for the `grafana/grafana` repository within the current time range. - Owner: `grafana` - Repository: `grafana` + +#### Response + +| Name | Description | +|--------------|-------------| +| starred_at | When the user starred the repository: YYYY-MM-DD HH:MM:SS | +| start_count | Current total of stars for the repository at the time of the event | +| id | node_id - a unique identifier for the GitHub user which can be used in GitHub's GraphQL API | +| login | GitHub handle of the user who starred the repository | +| git_name | Name of the GitHub user who starred the repository | +| company | Company name of the GitHub user who starred the repository | +| email | Email address of the GitHub user who starred the repository | +| url | URL to the GitHub profile for the user who starred the repository | + ### Workflows List GitHub Actions workflows defined in a repository. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Time Field | The time field to filter the responses on - can be: `CreatedAt` or `UpdatedAt | Yes | ##### Sample queries -Show all workflows for the `grafana/grafana` repository. +Show all workflows created within the `grafana/grafana` repository within the current time range. - Owner: `grafana` - Repository: `grafana` +- Time Field: `CreatedAt` + + +#### Response + +| Name | Description | +|------------|-------------| +| id | Unique identifier for the workflow | +| name | Name of the workflow | +| path | Path to the workflow YAML file in the repository | +| state | State of the workflow, can be: `active`, `deleted`, `disabled_fork`, `disabled_inactivity`, or `disabled_manually` | +| created_at | When the workflow was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the workflow was last updated: YYYY-MM-DD HH:MM:SS | +| url | API URL for the workflow | +| html_url | URL to the workflow file in the repository | +| badge_url | URL to the workflow status badge | ### Workflow usage @@ -544,17 +579,43 @@ Retrieve usage statistics for a workflow, such as run counts and durations. #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **Workflow**: The workflow to get usage for. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Workflow | The workflow ID or file name. Use `id` or the filename from `path` from [workflows](#workflows) queries | + ##### Sample queries -Show usage statistics for the `CI` workflow in the `grafana/grafana` repository. +Show usage statistics for the `Levitate` detect breaking changes workflow in the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -- Workflow: `CI` +- Workflow: `detect-breaking-changes-levitate.yml` + +#### Response +| Name | Description | +|-----------------------------|-------------| +| name | Name of the workflow (or workflow job) | +| unique triggering actors | Number of unique users or actors who triggered runs of this workflow | +| runs | Total number of workflow runs in the selected period | +| current billing cycle cost (approx.) | Approximate cost for the current billing cycle (if applicable) | +| skipped | Number (and percentage) of runs that were skipped | +| successes | Number (and percentage) of successful runs | +| failures | Number (and percentage) of failed runs | +| cancelled | Number (and percentage) of cancelled runs | +| total run duration (approx.)| Total duration of all runs (formatted as hours, minutes, seconds) | +| longest run duration (approx.) | Duration of the longest single run | +| average run duration (approx.) | Average duration of all runs | +| p95 run duration (approx.) | 95th percentile run duration | +| runs on Sunday | Number of runs started on Sunday | +| runs on Monday | Number of runs started on Monday | +| runs on Tuesday | Number of runs started on Tuesday | +| runs on Wednesday | Number of runs started on Wednesday | +| runs on Thursday | Number of runs started on Thursday | +| runs on Friday | Number of runs started on Friday | +| runs on Saturday | Number of runs started on Saturday | ### Workflow runs @@ -562,19 +623,34 @@ List runs for a specific workflow, including status, conclusion, and timing info #### Query options -- **Owner**: The GitHub user or organization that owns the repository. -- **Repository**: The name of the repository. -- **Workflow**: The workflow to list runs for. -- **Branch**: (Optional) Filter by branch. -- **Status**: (Optional) Filter by status (`queued`, `in_progress`, `completed`). -- **Conclusion**: (Optional) Filter by conclusion (`success`, `failure`, etc.). -- **Created**: (Optional) Filter by creation date. +| Name | Description | Required (yes/no) | +| ---- | ----------- | ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Workflow | | Yes | +| Branch | The head branch to filter on | No | ##### Sample queries -Show all completed runs for the `CI` workflow on the `main` branch in the `grafana/grafana` repository. +Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository. - Owner: `grafana` - Repository: `grafana` -- Workflow: `CI` -- Branch: `main` -- Status: `completed` +- Workflow: `detect-breaking-changes-levitate.yml` + +#### Response + +| Name | Description | +|--------------|-------------| +| id | Unique identifier for the workflow run | +| name | Name of the workflow or workflow job | +| head_branch | Name of the branch the workflow run was triggered on | +| head_sha | Commit SHA that triggered the workflow run | +| created_at | When the workflow run was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the workflow run was last updated: YYYY-MM-DD HH:MM:SS | +| html_url | URL to the workflow run in the GitHub web UI | +| url | API URL for the workflow run | +| status | Current status of the workflow run, can be: `queued`, `in_progress`, `completed`, `waiting`, `requested` or `pending | +| conclusion | Final conclusion of the workflow run, can be `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out` or action_required | +| event | Event that triggered the workflow run (e.g., push, pull_request) - see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) | +| workflow_id | Unique identifier for the workflow definition | +| run_number | The run number for this workflow run in the repository | From e1f6de6020d3b723da14092fd053a2e1a3d00e06 Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 20 May 2025 10:19:30 +0100 Subject: [PATCH 11/17] wip starting to tidy --- docs/sources/query/_index.md | 127 +++++++++++++++++------------------ 1 file changed, 63 insertions(+), 64 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index d7fb80c2..f3ec2979 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -45,20 +45,20 @@ Retrieve a list of commits for a repository or branch, including commit messages #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository. | Yes | -| Repository | The name of the repository | Yes | -| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | +| Name | Description | Required (yes/no) | +| -------------------| --------------------------------------------------------- | ------------------| +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | ##### Sample queries -Show all commits to the `main` branch of the `grafana/grafana` repository. +Show all commits to the `main` branch of the `grafana/grafana` repository: - Owner: `grafana` - Repository: `grafana` - Ref: `main` -Show all commits against a tag +Show all commits against a tag: - Owner: `grafana` - Repository: `grafana` @@ -66,15 +66,15 @@ Show all commits against a tag #### Response -| Name | Description | -| ---- | ----------- | -| id | commit ID | -| author | Name of the commit author | -| author_login | GitHub handle of the commit author | -| author_company | Company name of the commit author | -| committed_at | YYYY-MM-DD HH:MM:SS | -| pushed_at | YYYY-MM-DD HH:MM:SS | -| message | commit message | +| Name | Description | +| -------------- | -------------------------------------------------- | +| id | commit ID | +| author | Name of the commit author | +| author_login | GitHub handle of the commit author | +| author_company | Company name of the commit author | +| committed_at | When the change was committed: YYYY-MM-DD HH:MM:SS | +| pushed_at | When the commit was pushed: YYYY-MM-DD HH:MM:SS | +| message | The commit message | ### Issues @@ -82,39 +82,40 @@ List issues in a repository using the GitHub query syntax to filter the response #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | A GitHub user or organization | Yes | -| Repository | The name of a repository | No | -| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | -| Time field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` | +| Name | Description | Required (yes/no) | +| -------------------| ----------------------------- | ------------------| +| Owner | A GitHub user or organization | Yes | +| Repository | The name of a repository | No | +| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | +| Time field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` | Yes | ##### Sample queries -Show all closed issues labeled `type/bug` in the grafana repository. +Show all closed issues labeled `type/bug` in the grafana repository: - Owner: `grafana` - Repository: `grafana` - Query: `is:closed label:type/bug` -Show all issues with 'sql expressions' in the title +Show all issues with 'sql expressions' in the title: + - Owner: `grafana` - Repository: `grafana` - Query: `sql expressions in:title` #### Response -| Name | Description | -| ---- | ----------- | -| title | Issue title | -| author | GitHub handle of the author | +| Name | Description | +| ---------------| ----------- | +| title | Issue title | +| author | GitHub handle of the author | | author_company | Company name of the commit author | -| repo | Issue repository | -| number | Issue number | -| closed | true / false | -| created_at | YYYY-MM-DD HH:MM:SS | -| closed_at | YYYY-MM-DD HH:MM:SS | -| updated_at | YYYY-MM-DD HH:MM:SS | -| labels | Array of labels i.e. [ "type/bug", "needs more info"] | +| repo | Issue repository | +| number | Issue number | +| closed | true / false | +| created_at | When the issue was created:YYYY-MM-DD HH:MM:SS | +| closed_at | When the issue was closed: YYYY-MM-DD HH:MM:SS | +| updated_at | When the issue was last updated :YYYY-MM-DD HH:MM:SS | +| labels | Array of labels i.e. [ "type/bug", "needs more info"] | {{< admonition type="note" >}} This query returns a maximum of 1000 results. @@ -126,19 +127,19 @@ Get a list of contributors to an organization or repository. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository. | Yes | -| Repository | The name of a repository. | No | -| Query | Filter for contributors by name or GitHub handle | No | +| Name | Description | Required (yes/no) | +| -------------------| --------------------------------------------------------- | ------------------| +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter for contributors by name or GitHub handle | No | ##### Sample queries -Show all contributors to the `grafana` repository. +Show all contributors to the `grafana` repository: - Owner: `grafana` - Repository: `grafana` -Search for contributors with `bob` in their name or handle +Search for contributors with `bob` in their name or handle: - Owner: `grafana` - Repository: `grafana` @@ -166,13 +167,13 @@ List created tags for a repository. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository. | Yes | +| Name | Description | Required (yes/no) | +| ---------- | ---------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries -Show all tags created for the `grafana` repository within the current selected time range. +Show all tags created for the `grafana` repository within the current selected time range: - Owner: `grafana` - Repository: `grafana` @@ -197,10 +198,10 @@ List created releases for a repository. | Name | Description | Required (yes/no) | | ---- | ----------- | ----------------- | | Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository. | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries -Show all releases for the `grafana/grafana` repository. +Show all releases for the `grafana/grafana` repository: - Owner: `grafana` - Repository : `grafana` @@ -233,7 +234,7 @@ List pull requests for a repository, using the GitHub query syntax to filter the ##### Sample queries -Show all open pull requests authored by renovate in the `grafana/plugin-tools` repository. +Show all open pull requests authored by renovate in the `grafana/plugin-tools` repository: - Owner : `grafana` - Repository : `grafana` @@ -277,7 +278,7 @@ Get all labels defined in a repository, useful for categorizing issues and pull | Query | Filter on text in name and description for labels | No | ##### Sample queries -Show all labels for the `grafana/grafana` repository. +Show all labels for the `grafana/grafana` repository: - Owner: `grafana` - Repository: `grafana` @@ -303,7 +304,7 @@ List repositories for a user or organization. | Repository | The name of the repository - can be used for getting details on a single repository | No | ##### Sample queries -Show all repositories for the `grafana` organization. +Show all repositories for the `grafana` organization: - Organization: `grafana` @@ -338,7 +339,7 @@ Retrieve milestones for a repository, which can be used to group issues and pull | Query | Filter on text in the milestone title | No | ##### Sample queries -Show all milestones for the `grafana/grafana` repository for v11 of Grafana +Show all milestones for the `grafana/grafana` repository for v11 of Grafana: - Owner: `grafana` - Repository: `grafana` @@ -378,7 +379,7 @@ List packages published from a repository in an organization ##### Sample queries -Show all packages uploaded t the `grafana` organization. +Show all packages uploaded to the `grafana` organization: - Organization: `grafana` @@ -411,13 +412,11 @@ Query security vulnerabilities detected in a repository. ##### Sample queries -Show all security advisories for the `grafana/grafana` repository. +Show all security advisories for the `grafana/grafana` repository: - Owner: `grafana` - Repository: `grafana` - When the vulnerability was : YYYY-MM-DD HH:MM:SS - #### Response | Name | Description | @@ -452,12 +451,12 @@ List projects associated with a user or organization. | Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | ##### Sample queries -Show all projects for the `grafana/grafana` repository. +Show all projects for the `grafana/grafana` repository: - Project Owner: `organization` - Organization: `grafana` -Show all pull requests for the "Dashboards" project in the Grafana organization +Show all pull requests for the "Dashboards" project in the Grafana organization: - Project Owner: `organization` - Organization: `grafana` @@ -520,7 +519,7 @@ Get a list of users who have starred a repository, including being able to plot | Repository | The name of the repository | Yes | ##### Sample queries -Show all stargazers for the `grafana/grafana` repository within the current time range. +Show all stargazers for the `grafana/grafana` repository within the current time range: - Owner: `grafana` - Repository: `grafana` @@ -552,7 +551,7 @@ List GitHub Actions workflows defined in a repository. | Time Field | The time field to filter the responses on - can be: `CreatedAt` or `UpdatedAt | Yes | ##### Sample queries -Show all workflows created within the `grafana/grafana` repository within the current time range. +Show all workflows created within the `grafana/grafana` repository within the current time range: - Owner: `grafana` - Repository: `grafana` @@ -587,7 +586,7 @@ Retrieve usage statistics for a workflow, such as run counts and durations. ##### Sample queries -Show usage statistics for the `Levitate` detect breaking changes workflow in the `grafana/grafana` repository. +Show usage statistics for the `Levitate` detect breaking changes workflow in the `grafana/grafana` repository: - Owner: `grafana` - Repository: `grafana` @@ -627,11 +626,11 @@ List runs for a specific workflow, including status, conclusion, and timing info | ---- | ----------- | ----------------- | | Owner | The GitHub user or organization that owns the repository | Yes | | Repository | The name of the repository | Yes | -| Workflow | | Yes | +| Workflow | The workflow ID or file name. Use `id` or the filename from `path` from [workflows](#workflows) queries | Yes | | Branch | The head branch to filter on | No | ##### Sample queries -Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository. +Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository: - Owner: `grafana` - Repository: `grafana` From 74a24ac497a14ef513773d1a3d26c2ed78943b33 Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 20 May 2025 10:22:43 +0100 Subject: [PATCH 12/17] wip - more tidy up --- docs/sources/query/_index.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index f3ec2979..76ec5a61 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -180,14 +180,14 @@ Show all tags created for the `grafana` repository within the current selected t #### Response -| Name | Description | -| ---- | ----------- | -| name | Name of tag | -| id | Sha for the tag| -| author | Name of the GitHub user who created the tag | -| author_login | GitHub handle of the GitHub user who created the tag | -| author_company | Company name of the GitHub user who created the tag | -| date | YYYY-MM-DD HH:MM:SS | +| Name | Description | +|----------------|-----------------------------------------------------| +| name | Name of the tag | +| id | SHA for the tag | +| author | Name of the user who created the tag | +| author_login | GitHub handle of the user who created the tag | +| author_company | Company name of the user who created the tag | +| date | When the tag was created: YYYY-MM-DD HH:MM:SS | ### Releases @@ -544,11 +544,11 @@ List GitHub Actions workflows defined in a repository. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Time Field | The time field to filter the responses on - can be: `CreatedAt` or `UpdatedAt | Yes | +| Name | Description | Required (yes/no) | +|------------|-----------------------------------------------------|-------------------| +| owner | GitHub user or organization that owns the repository| Yes | +| repository | Name of the repository | Yes | +| Time Field | The time field to filter the responses on, can be: `CreatedAt` or `UpdatedAt | Yes | ##### Sample queries Show all workflows created within the `grafana/grafana` repository within the current time range: From c32cccab8becebb81e4fa9f793090679c01bf44c Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 20 May 2025 10:34:00 +0100 Subject: [PATCH 13/17] wip tidy up to pull requests query --- docs/sources/query/_index.md | 58 ++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 76ec5a61..c5e0ad02 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -147,15 +147,15 @@ Search for contributors with `bob` in their name or handle: #### Response -| Name | Description | -| ---- | ----------- | -| name | Name of the contributor | -| author | Name of the commit author | -| author_login | GitHub handle of the commit author | -| author_company | Company name of the commit author | -| committed_at | YYYY-MM-DD HH:MM:SS | -| pushed_at | YYYY-MM-DD HH:MM:SS | -| message | commit message | +| Name | Description | +|----------------|-------------------------------------------------| +| name | Name of the contributor | +| author | Name of the commit author | +| author_login | GitHub handle of the commit author | +| author_company | Company name of the commit author | +| committed_at | When the commit was made: YYYY-MM-DD HH:MM:SS | +| pushed_at | When the commit was pushed: YYYY-MM-DD HH:MM:SS | +| message | Commit message | {{< admonition type="note" >}} This query returns a maximum of 200 results. @@ -195,10 +195,10 @@ List created releases for a repository. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | +| Name | Description | Required (yes/no) | +| ---------- | ---------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries Show all releases for the `grafana/grafana` repository: @@ -208,16 +208,16 @@ Show all releases for the `grafana/grafana` repository: #### Response -| Name | Description | -| ---- | ----------- | -| name | Name of release | -| created_by | Name of the GitHub user who created the release | -| is_draft | true / false| -| is_prerelease | true / false| -| tag | Tag name associated with the release | -| url | URL for the tag associated with the release | -| created_at | YYYY-MM-DD HH:MM:SS | -| published_at | YYYY-MM-DD HH:MM:SS | +| Name | Description | +| --------------| ----------- | +| name | Name of release | +| created_by | Name of the GitHub user who created the release | +| is_draft | Whether the release is a draft release: `true` / `false` | +| is_prerelease | Whether the release is a pre-release: `true` / `false| +| tag | Tag name associated with the release | +| url | URL for the tag associated with the release | +| created_at | When the release was created: YYYY-MM-DD HH:MM:SS | +| published_at | When the release was published : YYYY-MM-DD HH:MM:SS | ### Pull requests @@ -225,12 +225,12 @@ List pull requests for a repository, using the GitHub query syntax to filter the #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | No | -| Query | | No | -| Time field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt`, `UpdatedAt` or `none` | +| Name | Description | Required (yes/no) | +| -------------------| ----------------------------- | ------------------| +| Owner | A GitHub user or organization | Yes | +| Repository | The name of a repository | No | +| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | +| Time Field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt`, `UpdatedAt` or `none` | Yes | ##### Sample queries From a6ff121703ed3e14a35f25632a244c79b5fe3a75 Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 20 May 2025 11:27:04 +0100 Subject: [PATCH 14/17] final tidy --- docs/sources/query/_index.md | 218 +++++++++++++++++------------------ 1 file changed, 109 insertions(+), 109 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index c5e0ad02..f3cb59c1 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -68,7 +68,7 @@ Show all commits against a tag: | Name | Description | | -------------- | -------------------------------------------------- | -| id | commit ID | +| id | Commit ID | | author | Name of the commit author | | author_login | GitHub handle of the commit author | | author_company | Company name of the commit author | @@ -213,7 +213,7 @@ Show all releases for the `grafana/grafana` repository: | name | Name of release | | created_by | Name of the GitHub user who created the release | | is_draft | Whether the release is a draft release: `true` / `false` | -| is_prerelease | Whether the release is a pre-release: `true` / `false| +| is_prerelease | Whether the release is a pre-release: `true` / `false` | | tag | Tag name associated with the release | | url | URL for the tag associated with the release | | created_at | When the release was created: YYYY-MM-DD HH:MM:SS | @@ -234,7 +234,7 @@ List pull requests for a repository, using the GitHub query syntax to filter the ##### Sample queries -Show all open pull requests authored by renovate in the `grafana/plugin-tools` repository: +Show all open pull requests authored by Renovate in the `grafana/plugin-tools` repository: - Owner : `grafana` - Repository : `grafana` @@ -271,11 +271,11 @@ Get all labels defined in a repository, useful for categorizing issues and pull #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Query | Filter on text in name and description for labels | No | +| Name | Description | Required (yes/no) | +| ---------- | ---------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter on text in name and description for labels | No | ##### Sample queries Show all labels for the `grafana/grafana` repository: @@ -285,11 +285,11 @@ Show all labels for the `grafana/grafana` repository: #### Response -| Name | Description | -| ---- | ----------- | -| Name | Description | -| color | Hexadecimal number | -| name | Label name | +| Name | Description | +| ----------- | ----------- | +| name | Description | +| color | Hexadecimal number | +| name | Label name | | description | Label description | ### Repositories @@ -298,10 +298,10 @@ List repositories for a user or organization. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository - can be used for getting details on a single repository | No | +| Name | Description | Required (yes/no) | +| -------------------| ------------------------------------ | ------------------| +| Owner | A GitHub user or organization | Yes | +| Repository | Filter on the name of the repository | No | ##### Sample queries Show all repositories for the `grafana` organization: @@ -310,16 +310,16 @@ Show all repositories for the `grafana` organization: #### Response -| Name | Description | -| ---- | ----------- | -| Name | Name of the repository | -| Owner | Organization or user who owns the repository | -| Name_with_owner| Returns the owner and repository name in the format / i.e. `grafana/loki` | -| Url | URL for the repository | -| Forks | The number of forks for a repository | -| Is_mirror | Whether the repository is a mirror of another repository: `true` / `false` | -| is_private | Whether the repository is private: `true` / `false` | -| created_at | When the repository was created: YYYY-MM-DD HH:MM:SS | +| Name | Description | +| -------------- | ----------- | +| name | Name of the repository | +| owner | Organization or user who owns the repository | +| name_with_owner| Returns the owner and repository name in the format `/` i.e. `grafana/loki` | +| url | URL for the repository | +| forks | The number of forks for a repository | +| is_mirror | Whether the repository is a mirror of another repository: `true` / `false` | +| is_private | Whether the repository is private: `true` / `false` | +| created_at | When the repository was created: YYYY-MM-DD HH:MM:SS | {{< admonition type="note" >}} @@ -332,11 +332,11 @@ Retrieve milestones for a repository, which can be used to group issues and pull #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Query | Filter on text in the milestone title | No | +| Name | Description | Required (yes/no) | +| ---------- | ---------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter on text in the milestone title | No | ##### Sample queries Show all milestones for the `grafana/grafana` repository for v11 of Grafana: @@ -347,15 +347,15 @@ Show all milestones for the `grafana/grafana` repository for v11 of Grafana: #### Response -| Name | Description | -| ---- | ----------- | -| title | Milestone title | -| author | GitHub handle of the user who created the milestone | -| closed | Whether the milestone is closed: `true` / `false` | -| state | One of `OPEN` or `CLOSED` | +| Name | Description | +| ---------- | ----------- | +| title | Milestone title | +| author | GitHub handle of the user who created the milestone | +| closed | Whether the milestone is closed: `true` / `false` | +| state | One of `OPEN` or `CLOSED` | | created_at | When the milestone was created: YYYY-MM-DD HH:MM:SS | -| closed_at | When the milestone was closed: YYYY-MM-DD HH:MM:SS | -| due_at | When the milestone is due by: YYYY-MM-DD HH:MM:SS | +| closed_at | When the milestone was closed: YYYY-MM-DD HH:MM:SS | +| due_at | When the milestone is due by: YYYY-MM-DD HH:MM:SS | {{< admonition type="note" >}} Milestone titles can be anything and are therefore parsed as a string. @@ -370,12 +370,12 @@ List packages published from a repository in an organization #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Package type | One of: `MAVEN`, `DOCKER`, `DEBIAN` or `PYPI` | Yes | -| Names | Filter for packages using a comma separated list of names | No | +| Name | Description | Required (yes/no) | +| ------------ | ----------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Package type | One of: `MAVEN`, `DOCKER`, `DEBIAN` or `PYPI` | Yes | +| Names | Filter for packages using a comma separated list of names | No | ##### Sample queries @@ -385,8 +385,8 @@ Show all packages uploaded to the `grafana` organization: #### Response -| Name | Description | -| ---- | ----------- | +| Name | Description | +| ---------- | ----------- | | name | Package name | | platform | Platform or registry where the package is published | | version | Package version | @@ -404,10 +404,10 @@ Query security vulnerabilities detected in a repository. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | +| Name | Description | Required (yes/no) | +| ------------ | ----------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | @@ -442,13 +442,13 @@ List projects associated with a user or organization. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Project Owner | One of `Organization` or `User` | Yes | -| Organization | Organization for the Project (shown when Organization was previously selected) | Yes | -| User | User for the Project (shown when User was previously selected) | Yes | +| Name | Description | Required (yes/no) | +| -------------- | ----------- | ----------------- | +| Project Owner | One of `Organization` or `User` | Yes | +| Organization | Organization for the Project (shown when Organization was previously selected) | Yes | +| User | User for the Project (shown when User was previously selected) | Yes | | Project Number | Enter a specific Project Number to query for associated items | No | -| Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | +| Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | ##### Sample queries Show all projects for the `grafana/grafana` repository: @@ -467,16 +467,16 @@ Show all pull requests for the "Dashboards" project in the Grafana organization: ##### When no Project Number is specified -| Name | Description | -|--------------|-------------| -| number| The project number | -| title | Title of the project | -| url | URL for the project | -| closed | Whether the project has been closed: `true`/ `false` | -| public | Whether the project is public: `true` / `false | -| closed_at | When the project was closed: YYYY-MM-DD HH:MM:SS | -| updated_at | When the project was last updated | -| created_at | When the project was created | +| Name | Description | +|-------------------|-------------| +| number | The project number | +| title | Title of the project | +| url | URL for the project | +| closed | Whether the project has been closed: `true`/ `false` | +| public | Whether the project is public: `true` / `false` | +| closed_at | When the project was closed: YYYY-MM-DD HH:MM:SS | +| updated_at | When the project was last updated | +| created_at | When the project was created | | short_description | The description of the project | {{< admonition type="note" >}} @@ -489,22 +489,22 @@ GitHub Projects allow for customization of default fields and custom fields to b therefore the response can vary significantly between projects." {{< /admonition >}} -| Name | Description | -|--------------|-------------| -| name | Name of the project item (issue or pull request) | -| id | Unique identifier for the project item | -| type | Type of the item (e.g., ISSUE, PULL_REQUEST) | -| status | Status of the item (e.g., "In development", "Shipped") - this can be configured on the project | -| labels | Comma-separated list of labels assigned to the item | -| assignees | Comma-separated list of users assigned to the item | -| reviewers | Comma-separated list of reviewers (for pull requests) | -| repository | Name of the repository the item belongs to | -| milestone | Milestone associated with the item | -| priority | Priority value or label | -| archived | Whether the item is archived: `true` / `false` | -| created_at | When the item was created: YYYY-MM-DD HH:MM:SS | -| updated_at | When the item was last updated: YYYY-MM-DD HH:MM:SS | -| closed_at | When the item was closed, if applicable: YYYY-MM-DD HH:MM:SS | +| Name | Description | +|-----------------|-------------| +| name | Name of the project item (issue or pull request) | +| id | Unique identifier for the project item | +| type | Type of the item (such as ISSUE, PULL_REQUEST) | +| status | Status of the item (such as "In development", "Shipped") - this can be configured on the project | +| labels | Comma-separated list of labels assigned to the item | +| assignees | Comma-separated list of users assigned to the item | +| reviewers | Comma-separated list of reviewers (for pull requests) | +| repository | Name of the repository the item belongs to | +| milestone | Milestone associated with the item | +| priority | Priority value or label | +| archived | Whether the item is archived: `true` / `false` | +| created_at | When the item was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the item was last updated: YYYY-MM-DD HH:MM:SS | +| closed_at | When the item was closed, if applicable: YYYY-MM-DD HH:MM:SS | | (custom fields) | Any custom defined fields will also be returned alongside their values | ### Stargazers @@ -513,10 +513,10 @@ Get a list of users who have starred a repository, including being able to plot #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | +| Name | Description | Required (yes/no) | +| ------------ | ----------------------------------------------------------| ----------------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries Show all stargazers for the `grafana/grafana` repository within the current time range: @@ -527,16 +527,16 @@ Show all stargazers for the `grafana/grafana` repository within the current time #### Response -| Name | Description | -|--------------|-------------| -| starred_at | When the user starred the repository: YYYY-MM-DD HH:MM:SS | +| Name | Description | +|-------------|-------------| +| starred_at | When the user starred the repository: YYYY-MM-DD HH:MM:SS | | start_count | Current total of stars for the repository at the time of the event | -| id | node_id - a unique identifier for the GitHub user which can be used in GitHub's GraphQL API | -| login | GitHub handle of the user who starred the repository | -| git_name | Name of the GitHub user who starred the repository | -| company | Company name of the GitHub user who starred the repository | -| email | Email address of the GitHub user who starred the repository | -| url | URL to the GitHub profile for the user who starred the repository | +| id | node_id - a unique identifier for the GitHub user which can be used in GitHub's GraphQL API | +| login | GitHub handle of the user who starred the repository | +| git_name | Name of the GitHub user who starred the repository | +| company | Company name of the GitHub user who starred the repository | +| email | Email address of the GitHub user who starred the repository | +| url | URL to the GitHub profile for the user who starred the repository | ### Workflows @@ -548,7 +548,7 @@ List GitHub Actions workflows defined in a repository. |------------|-----------------------------------------------------|-------------------| | owner | GitHub user or organization that owns the repository| Yes | | repository | Name of the repository | Yes | -| Time Field | The time field to filter the responses on, can be: `CreatedAt` or `UpdatedAt | Yes | +| Time Field | The time field to filter the responses on, can be: `CreatedAt` or `UpdatedAt` | Yes | ##### Sample queries Show all workflows created within the `grafana/grafana` repository within the current time range: @@ -578,11 +578,11 @@ Retrieve usage statistics for a workflow, such as run counts and durations. #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Workflow | The workflow ID or file name. Use `id` or the filename from `path` from [workflows](#workflows) queries | +| Name | Description | Required (yes/no) | +|------------|-----------------------------------------------------|-------------------| +| 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 | ##### Sample queries @@ -622,12 +622,12 @@ List runs for a specific workflow, including status, conclusion, and timing info #### Query options -| Name | Description | Required (yes/no) | -| ---- | ----------- | ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Workflow | The workflow ID or file name. Use `id` or the filename from `path` from [workflows](#workflows) queries | Yes | -| Branch | The head branch to filter on | No | +| Name | Description | Required (yes/no) | +|------------|-----------------------------------------------------|-------------------| +| 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 | +| Branch | The head branch to filter on | No | ##### Sample queries Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository: From 4a5b0d25891330ea69c52b6ca05f1c1106776f6c Mon Sep 17 00:00:00 2001 From: David Harris Date: Wed, 21 May 2025 13:26:55 +0100 Subject: [PATCH 15/17] fixes from review --- docs/sources/query/_index.md | 47 +++++++++---------- docs/sources/variables-and-macros/macros.md | 2 +- .../sources/variables-and-macros/variables.md | 2 +- 3 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index f3cb59c1..17e425ee 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -22,7 +22,7 @@ The GitHub data source plugin for Grafana enables you to query and visualize dat The data source supports the following queries, which you can select from in the query editor under the `Query Type` dropdown: -- [**Commits**](#commits): Retrieve a list of commits for a repository or branch, including commit message, author, and timestamp. +- [**Commits**](#commits): Retrieve a list of commits for a branch or ref within a repository, including commit message, author, and timestamp. - [**Issues**](#issues): List issues in a repository, using the GitHub query syntax to filter the response. - [**Contributors**](#contributors): Get a list of contributors to a repository. - [**Tags**](#tags): List created tags for a repository. @@ -41,7 +41,7 @@ The data source supports the following queries, which you can select from in the ### Commits -Retrieve a list of commits for a repository or branch, including commit messages, authors, and timestamps. Useful for tracking code changes, deployment activity, or contributor history. +Retrieve a list of commits for a branch or ref within a repository, including commit message, author, and timestamp. Useful for tracking code changes, deployment activity, or contributor history. #### Query options @@ -80,6 +80,10 @@ Show all commits against a tag: List issues in a repository using the GitHub query syntax to filter the response. Useful for tracking open bugs, feature requests, or project tasks. +{{< admonition type="note" >}} +This query returns a maximum of 1000 results. +{{< /admonition >}} + #### Query options | Name | Description | Required (yes/no) | @@ -117,14 +121,14 @@ Show all issues with 'sql expressions' in the title: | updated_at | When the issue was last updated :YYYY-MM-DD HH:MM:SS | | labels | Array of labels i.e. [ "type/bug", "needs more info"] | -{{< admonition type="note" >}} -This query returns a maximum of 1000 results. -{{< /admonition >}} - ### Contributors Get a list of contributors to an organization or repository. +{{< admonition type="note" >}} +This query returns a maximum of 200 results. +{{< /admonition >}} + #### Query options | Name | Description | Required (yes/no) | @@ -157,10 +161,6 @@ Search for contributors with `bob` in their name or handle: | pushed_at | When the commit was pushed: YYYY-MM-DD HH:MM:SS | | message | Commit message | -{{< admonition type="note" >}} -This query returns a maximum of 200 results. -{{< /admonition >}} - ### Tags List created tags for a repository. @@ -296,6 +296,10 @@ Show all labels for the `grafana/grafana` repository: List repositories for a user or organization. +{{< admonition type="note" >}} +This query returns a maximum of 1000 results. +{{< /admonition >}} + #### Query options | Name | Description | Required (yes/no) | @@ -321,11 +325,6 @@ Show all repositories for the `grafana` organization: | is_private | Whether the repository is private: `true` / `false` | | created_at | When the repository was created: YYYY-MM-DD HH:MM:SS | - -{{< admonition type="note" >}} -This query returns a maximum of 1000 results. -{{< /admonition >}} - ### Milestones Retrieve milestones for a repository, which can be used to group issues and pull requests. @@ -366,7 +365,11 @@ can be used to change the data type in this scenario. ### Packages -List packages published from a repository in an organization +List packages published from a repository in an organization. + +{{< admonition type="note" >}} +This query does not support querying npm, RubyGems or NuGet packages. +{{< /admonition >}} #### Query options @@ -394,10 +397,6 @@ Show all packages uploaded to the `grafana` organization: | prerelease | Whether the package version is a prerelease: `true` / `false` | | downloads | Number of downloads for the package version | -{{< admonition type="note" >}} -This query does not support querying npm, RubyGems or NuGet packages. -{{< /admonition >}} - ### Vulnerabilities Query security vulnerabilities detected in a repository. @@ -440,6 +439,10 @@ Show all security advisories for the `grafana/grafana` repository: List projects associated with a user or organization. +{{< admonition type="note" >}} +This query returns a maximum of 200 results. +{{< /admonition >}} + #### Query options | Name | Description | Required (yes/no) | @@ -479,10 +482,6 @@ Show all pull requests for the "Dashboards" project in the Grafana organization: | created_at | When the project was created | | short_description | The description of the project | -{{< admonition type="note" >}} -This query returns a maximum of 200 results. -{{< /admonition >}} - ##### When a Project Number is specified {{< admonition type="note" >}} GitHub Projects allow for customization of default fields and custom fields to be added, diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index ebee6ee4..8323e7e5 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -12,7 +12,7 @@ labels: - oss - enterprise - cloud -weight: 202 +weight: 302 --- # Use macros with GitHub data source plugin for Grafana diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index 24e0dd3e..91e5b0d6 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -12,7 +12,7 @@ labels: - oss - enterprise - cloud -weight: 201 +weight: 301 --- # Create variable with GitHub data source plugin for Grafana From 34dae2cb1248d0ff56c416a45178c6b790f011af Mon Sep 17 00:00:00 2001 From: David Harris Date: Tue, 27 May 2025 11:16:26 +0100 Subject: [PATCH 16/17] gemini writers-toolkit suggestions --- docs/sources/query/_index.md | 557 +++++++++++++++++------------------ 1 file changed, 274 insertions(+), 283 deletions(-) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 17e425ee..13c657e3 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -7,6 +7,8 @@ keywords: - github - github repository - API + - query + - visualize labels: products: - oss @@ -20,7 +22,7 @@ The GitHub data source plugin for Grafana enables you to query and visualize dat ## Query types -The data source supports the following queries, which you can select from in the query editor under the `Query Type` dropdown: +The data source supports the following query types, which you can select from the `Query Type` dropdown in the query editor: - [**Commits**](#commits): Retrieve a list of commits for a branch or ref within a repository, including commit message, author, and timestamp. - [**Issues**](#issues): List issues in a repository, using the GitHub query syntax to filter the response. @@ -34,7 +36,7 @@ The data source supports the following queries, which you can select from in the - [**Packages**](#packages): List packages published from a repository in an organization. - [**Vulnerabilities**](#vulnerabilities): Query security vulnerabilities detected in a repository. - [**Projects**](#projects): List projects associated with a user or organization. -- [**Stargazers**](#stargazers): Get a list of users who have starred a repository, including being able to plot a total count over time. +- [**Stargazers**](#stargazers): Get a list of users who have starred a repository, including the ability to plot a total count over time. - [**Workflows**](#workflows): List GitHub Actions workflows defined in a repository. - [**Workflow usage**](#workflow-usage): Retrieve usage statistics for a workflow, such as run counts and durations. - [**Workflow runs**](#workflow-runs): List runs for a specific workflow, including status, conclusion, and timing information. @@ -45,11 +47,11 @@ Retrieve a list of commits for a branch or ref within a repository, including co #### Query options -| Name | Description | Required (yes/no) | -| -------------------| --------------------------------------------------------- | ------------------| -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | +| Name | Description | Required | +| ---------------- | --------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Ref (Branch/Tag) | The branch or tag to list commits against | Yes | ##### Sample queries Show all commits to the `main` branch of the `grafana/grafana` repository: @@ -78,7 +80,7 @@ Show all commits against a tag: ### Issues -List issues in a repository using the GitHub query syntax to filter the response. Useful for tracking open bugs, feature requests, or project tasks. +List issues in a repository using the GitHub query syntax to filter the response. Useful for tracking open bugs, feature requests, or project tasks. {{< admonition type="note" >}} This query returns a maximum of 1000 results. @@ -86,15 +88,15 @@ This query returns a maximum of 1000 results. #### Query options -| Name | Description | Required (yes/no) | -| -------------------| ----------------------------- | ------------------| -| Owner | A GitHub user or organization | Yes | -| Repository | The name of a repository | No | -| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | -| Time field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt` or `UpdatedAt` | Yes | +| Name | Description | Required | +| ---------- | ------------------------------------------------------------------------------- | -------- | +| Owner | A GitHub user or organization | Yes | +| Repository | The name of a repository | No | +| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | +| Time field | The time field to filter the responses on, can be: `CreatedAt`, `ClosedAt`, or `UpdatedAt` | Yes | -##### Sample queries -Show all closed issues labeled `type/bug` in the grafana repository: +##### Sample queries +Show all closed issues labeled `type/bug` in the Grafana repository: - Owner: `grafana` - Repository: `grafana` @@ -108,22 +110,22 @@ Show all issues with 'sql expressions' in the title: #### Response -| Name | Description | -| ---------------| ----------- | -| title | Issue title | -| author | GitHub handle of the author | -| author_company | Company name of the commit author | -| repo | Issue repository | -| number | Issue number | -| closed | true / false | -| created_at | When the issue was created:YYYY-MM-DD HH:MM:SS | +| Name | Description | +| -------------- | ---------------------------------------------- | +| title | Issue title | +| author | GitHub handle of the author | +| author_company | Company name of the commit author | +| repo | Issue repository | +| number | Issue number | +| closed | `true` or `false` | +| created_at | When the issue was created: YYYY-MM-DD HH:MM:SS | | closed_at | When the issue was closed: YYYY-MM-DD HH:MM:SS | -| updated_at | When the issue was last updated :YYYY-MM-DD HH:MM:SS | -| labels | Array of labels i.e. [ "type/bug", "needs more info"] | +| updated_at | When the issue was last updated: YYYY-MM-DD HH:MM:SS | +| labels | Array of labels, for example: `["type/bug", "needs more info"]` | ### Contributors -Get a list of contributors to an organization or repository. +Get a list of contributors to an organization or repository. {{< admonition type="note" >}} This query returns a maximum of 200 results. @@ -131,11 +133,11 @@ This query returns a maximum of 200 results. #### Query options -| Name | Description | Required (yes/no) | -| -------------------| --------------------------------------------------------- | ------------------| -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Query | Filter for contributors by name or GitHub handle | No | +| Name | Description | Required | +| ---------- | --------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter for contributors by name or GitHub handle | No | ##### Sample queries Show all contributors to the `grafana` repository: @@ -151,15 +153,15 @@ Search for contributors with `bob` in their name or handle: #### Response -| Name | Description | -|----------------|-------------------------------------------------| -| name | Name of the contributor | -| author | Name of the commit author | -| author_login | GitHub handle of the commit author | -| author_company | Company name of the commit author | -| committed_at | When the commit was made: YYYY-MM-DD HH:MM:SS | -| pushed_at | When the commit was pushed: YYYY-MM-DD HH:MM:SS | -| message | Commit message | +| Name | Description | +| -------------- | -------------------------------------------------- | +| name | Name of the contributor | +| author | Name of the commit author | +| author_login | GitHub handle of the commit author | +| author_company | Company name of the commit author | +| committed_at | When the commit was made: YYYY-MM-DD HH:MM:SS | +| pushed_at | When the commit was pushed: YYYY-MM-DD HH:MM:SS | +| message | Commit message | ### Tags @@ -167,27 +169,27 @@ List created tags for a repository. #### Query options -| Name | Description | Required (yes/no) | -| ---------- | ---------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | +| Name | Description | Required | +| ---------- | -------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries -Show all tags created for the `grafana` repository within the current selected time range: +Show all tags created for the `grafana` repository within the currently selected time range: - Owner: `grafana` - Repository: `grafana` #### Response -| Name | Description | -|----------------|-----------------------------------------------------| -| name | Name of the tag | -| id | SHA for the tag | -| author | Name of the user who created the tag | -| author_login | GitHub handle of the user who created the tag | -| author_company | Company name of the user who created the tag | -| date | When the tag was created: YYYY-MM-DD HH:MM:SS | +| Name | Description | +| -------------- | -------------------------------------------------- | +| name | Name of the tag | +| id | SHA for the tag | +| author | Name of the user who created the tag | +| author_login | GitHub handle of the user who created the tag | +| author_company | Company name of the user who created the tag | +| date | When the tag was created: YYYY-MM-DD HH:MM:SS | ### Releases @@ -195,29 +197,29 @@ List created releases for a repository. #### Query options -| Name | Description | Required (yes/no) | -| ---------- | ---------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | +| Name | Description | Required | +| ---------- | -------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries Show all releases for the `grafana/grafana` repository: - Owner: `grafana` -- Repository : `grafana` +- Repository: `grafana` #### Response -| Name | Description | -| --------------| ----------- | -| name | Name of release | +| Name | Description | +| ------------- | ---------------------------------------------- | +| name | Name of release | | created_by | Name of the GitHub user who created the release | -| is_draft | Whether the release is a draft release: `true` / `false` | -| is_prerelease | Whether the release is a pre-release: `true` / `false` | -| tag | Tag name associated with the release | -| url | URL for the tag associated with the release | +| is_draft | Whether the release is a draft release: `true` or `false` | +| is_prerelease | Whether the release is a pre-release: `true` or `false` | +| tag | Tag name associated with the release | +| url | URL for the tag associated with the release | | created_at | When the release was created: YYYY-MM-DD HH:MM:SS | -| published_at | When the release was published : YYYY-MM-DD HH:MM:SS | +| published_at | When the release was published: YYYY-MM-DD HH:MM:SS | ### Pull requests @@ -225,45 +227,45 @@ List pull requests for a repository, using the GitHub query syntax to filter the #### Query options -| Name | Description | Required (yes/no) | -| -------------------| ----------------------------- | ------------------| -| Owner | A GitHub user or organization | Yes | -| Repository | The name of a repository | No | -| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | -| Time Field | The time field to filter the responses on - can be: `CreatedAt`, `ClosedAt`, `UpdatedAt` or `none` | Yes | - +| Name | Description | Required | +| ---------- | ------------------------------------------------------------------------------- | -------- | +| Owner | A GitHub user or organization | Yes | +| Repository | The name of a repository | No | +| Query | Use GitHub's [query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) to filter results | No | +| Time Field | The time field to filter the responses on, can be: `CreatedAt`, `ClosedAt`, `UpdatedAt`, or `none` | Yes | ##### Sample queries Show all open pull requests authored by Renovate in the `grafana/plugin-tools` repository: -- Owner : `grafana` -- Repository : `grafana` +- Owner: `grafana` +- Repository: `grafana` - Query: `is:open author:app/renovate` - Time field: `none` #### Response -| Name | Description | -| ---- | ----------- | -| number | Pull request number | -| title | Pull request title | -| url | URL to the pull request | -| additions | Total number of lines of code that have been added or altered in the pull request | -| deletions | Total number of lines of code that have been removed or altered in the pull request | -| repository | Repository for the pull request | -| state | Can be `open`, `closed` or `merged` | -| author_name | Name of the GitHub user who created the pull request | -| author_login | GitHub handle of the GitHub user who created the pull request | -| author_email | Email address of the GitHub user who created the pull request | -| author_company | Company name of the GitHub user who created the pull request | -| closed | Whether the pull request is closed: `true` / `false` | -| is_draft | Whether the pull request is in draft: `true` / `false` | -| locked | Whether the pull request has been locked: `true` / `false` | -| merged | Whether the pull request has been merged | -| mergeable | Whether the pull request can be automatically merged: `MERGEABLE`, `CONFLICTING` or `UNKNOWN` | -| closed_at | When the pull request was closed: YYYY-MM-DD HH:MM:SS | -| merged_at | When the pull request was merged: YYYY-MM-DD HH:MM:SS | -| merged_by_name | Name of the GitHub user who merged the pull request | -| merged_by_login | GitHub handle of the GitHub user who merged the pull request | + +| Name | Description | +| --------------- | ------------------------------------------------------------------------ | +| number | Pull request number | +| title | Pull request title | +| url | URL to the pull request | +| additions | Total number of lines of code that have been added or altered in the pull request | +| deletions | Total number of lines of code that have been removed or altered in the pull request | +| repository | Repository for the pull request | +| state | Can be `open`, `closed`, or `merged` | +| author_name | Name of the GitHub user who created the pull request | +| author_login | GitHub handle of the GitHub user who created the pull request | +| author_email | Email address of the GitHub user who created the pull request | +| author_company | Company name of the GitHub user who created the pull request | +| closed | Whether the pull request is closed: `true` or `false` | +| is_draft | Whether the pull request is in draft: `true` or `false` | +| locked | Whether the pull request has been locked: `true` or `false` | +| merged | Whether the pull request has been merged | +| mergeable | Whether the pull request can be automatically merged: `MERGEABLE`, `CONFLICTING`, or `UNKNOWN` | +| closed_at | When the pull request was closed: YYYY-MM-DD HH:MM:SS | +| merged_at | When the pull request was merged: YYYY-MM-DD HH:MM:SS | +| merged_by_name | Name of the GitHub user who merged the pull request | +| merged_by_login | GitHub handle of the GitHub user who merged the pull request | ### Labels @@ -271,11 +273,11 @@ Get all labels defined in a repository, useful for categorizing issues and pull #### Query options -| Name | Description | Required (yes/no) | -| ---------- | ---------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Query | Filter on text in name and description for labels | No | +| Name | Description | Required | +| ---------- | -------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter on text in name and description for labels | No | ##### Sample queries Show all labels for the `grafana/grafana` repository: @@ -285,12 +287,11 @@ Show all labels for the `grafana/grafana` repository: #### Response -| Name | Description | -| ----------- | ----------- | -| name | Description | -| color | Hexadecimal number | -| name | Label name | -| description | Label description | +| Name | Description | +| ----------- | --------------------------------- | +| name | Label name | +| color | Hexadecimal number | +| description | Label description | ### Repositories @@ -302,10 +303,10 @@ This query returns a maximum of 1000 results. #### Query options -| Name | Description | Required (yes/no) | -| -------------------| ------------------------------------ | ------------------| -| Owner | A GitHub user or organization | Yes | -| Repository | Filter on the name of the repository | No | +| Name | Description | Required | +| ---------- | ------------------------------------ | -------- | +| Owner | A GitHub user or organization | Yes | +| Repository | Filter on the name of the repository | No | ##### Sample queries Show all repositories for the `grafana` organization: @@ -314,16 +315,16 @@ Show all repositories for the `grafana` organization: #### Response -| Name | Description | -| -------------- | ----------- | -| name | Name of the repository | -| owner | Organization or user who owns the repository | -| name_with_owner| Returns the owner and repository name in the format `/` i.e. `grafana/loki` | -| url | URL for the repository | -| forks | The number of forks for a repository | -| is_mirror | Whether the repository is a mirror of another repository: `true` / `false` | -| is_private | Whether the repository is private: `true` / `false` | -| created_at | When the repository was created: YYYY-MM-DD HH:MM:SS | +| Name | Description | +| --------------- | ---------------------------------------------------------- | +| name | Name of the repository | +| owner | Organization or user who owns the repository | +| name_with_owner | Returns the owner and repository name in the format `/`, for example: `grafana/loki` | +| url | URL for the repository | +| forks | The number of forks for a repository | +| is_mirror | Whether the repository is a mirror of another repository: `true` or `false` | +| is_private | Whether the repository is private: `true` or `false` | +| created_at | When the repository was created: YYYY-MM-DD HH:MM:SS | ### Milestones @@ -331,11 +332,11 @@ Retrieve milestones for a repository, which can be used to group issues and pull #### Query options -| Name | Description | Required (yes/no) | -| ---------- | ---------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Query | Filter on text in the milestone title | No | +| Name | Description | Required | +| ---------- | -------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Query | Filter on text in the milestone title | No | ##### Sample queries Show all milestones for the `grafana/grafana` repository for v11 of Grafana: @@ -346,21 +347,18 @@ Show all milestones for the `grafana/grafana` repository for v11 of Grafana: #### Response -| Name | Description | -| ---------- | ----------- | -| title | Milestone title | -| author | GitHub handle of the user who created the milestone | -| closed | Whether the milestone is closed: `true` / `false` | -| state | One of `OPEN` or `CLOSED` | -| created_at | When the milestone was created: YYYY-MM-DD HH:MM:SS | -| closed_at | When the milestone was closed: YYYY-MM-DD HH:MM:SS | -| due_at | When the milestone is due by: YYYY-MM-DD HH:MM:SS | +| Name | Description | +| ---------- | ---------------------------------------------- | +| title | Milestone title | +| author | GitHub handle of the user who created the milestone | +| closed | Whether the milestone is closed: `true` or `false` | +| state | One of `OPEN` or `CLOSED` | +| created_at | When the milestone was created: YYYY-MM-DD HH:MM:SS | +| closed_at | When the milestone was closed: YYYY-MM-DD HH:MM:SS | +| due_at | When the milestone is due by: YYYY-MM-DD HH:MM:SS | {{< admonition type="note" >}} -Milestone titles can be anything and are therefore parsed as a string. -This means sorting by title may appear incorrect if you have numeric milestones i.e. `12.0.0`. -[Transformations](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/) -can be used to change the data type in this scenario. +Milestone titles can be anything and are therefore parsed as a string. This means sorting by title may appear incorrect if you have numeric milestones, for example: `12.0.0`. [Transformations](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/) can be used to change the data type in this scenario. {{< /admonition >}} ### Packages @@ -368,18 +366,17 @@ can be used to change the data type in this scenario. List packages published from a repository in an organization. {{< admonition type="note" >}} -This query does not support querying npm, RubyGems or NuGet packages. +This query does not support querying npm, RubyGems, or NuGet packages. {{< /admonition >}} #### Query options -| Name | Description | Required (yes/no) | -| ------------ | ----------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | -| Package type | One of: `MAVEN`, `DOCKER`, `DEBIAN` or `PYPI` | Yes | -| Names | Filter for packages using a comma separated list of names | No | - +| Name | Description | Required | +| ------------ | --------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | +| Package type | One of: `MAVEN`, `DOCKER`, `DEBIAN`, or `PYPI` | Yes | +| Names | Filter for packages using a comma-separated list of names | No | ##### Sample queries Show all packages uploaded to the `grafana` organization: @@ -388,14 +385,14 @@ Show all packages uploaded to the `grafana` organization: #### Response -| Name | Description | -| ---------- | ----------- | -| name | Package name | -| platform | Platform or registry where the package is published | -| version | Package version | -| type | Package type (e.g., MAVEN, DOCKER, DEBIAN, PYPI) | -| prerelease | Whether the package version is a prerelease: `true` / `false` | -| downloads | Number of downloads for the package version | +| Name | Description | +| ---------- | ----------------------------------------------------------- | +| name | Package name | +| platform | Platform or registry where the package is published | +| version | Package version | +| type | Package type (e.g., `MAVEN`, `DOCKER`, `DEBIAN`, `PYPI`) | +| prerelease | Whether the package version is a prerelease: `true` or `false` | +| downloads | Number of downloads for the package version | ### Vulnerabilities @@ -403,12 +400,10 @@ Query security vulnerabilities detected in a repository. #### Query options -| Name | Description | Required (yes/no) | -| ------------ | ----------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | - - +| Name | Description | Required | +| ---------- | -------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries Show all security advisories for the `grafana/grafana` repository: @@ -418,22 +413,22 @@ Show all security advisories for the `grafana/grafana` repository: #### Response -| Name | Description | -|------------------------|-------------| +| Name | Description | +| ---------------------- | ------------------------------------------------------- | | value | Custom field which allows for counting or aggregation, always returns `1` | | created_at | When the vulnerability alert was created (when the vulnerability was published on GitHub): YYYY-MM-DD HH:MM:SS | | dismissed_at | When the vulnerability alert was dismissed, if applicable: YYYY-MM-DD HH:MM:SS | | dismissed_reason | Reason the vulnerability alert was dismissed (e.g., false positive, won't fix), if applicable | | withdrawn_at | When the advisory was withdrawn, if applicable: YYYY-MM-DD HH:MM:SS | -| packageName | Name of the affected package | -| advisoryDescription | Description of the vulnerability/advisory | +| packageName | Name of the affected package | +| advisoryDescription | Description of the vulnerability or advisory | | firstPatchedVersion | The first version of the package where the vulnerability is fixed | | vulnerableVersionRange | The range of package versions affected by the vulnerability | | cvssScore | CVSS (Common Vulnerability Scoring System) score for the vulnerability | -| cvssVector | CVSS vector string describing the scoring metrics | -| permalink | URL to the GitHub Security Advisory or alert | -| severity | Severity level of the vulnerability (e.g., LOW, MODERATE, HIGH, CRITICAL) | -| state | State of the vulnerability alert (e.g., OPEN, FIXED, DISMISSED) | +| cvssVector | CVSS vector string describing the scoring metrics | +| permalink | URL to the GitHub Security Advisory or alert | +| severity | Severity level of the vulnerability (e.g., `LOW`, `MODERATE`, `HIGH`, `CRITICAL`) | +| state | State of the vulnerability alert (e.g., `OPEN`, `FIXED`, `DISMISSED`) | ### Projects @@ -445,13 +440,13 @@ This query returns a maximum of 200 results. #### Query options -| Name | Description | Required (yes/no) | -| -------------- | ----------- | ----------------- | -| Project Owner | One of `Organization` or `User` | Yes | -| Organization | Organization for the Project (shown when Organization was previously selected) | Yes | -| User | User for the Project (shown when User was previously selected) | Yes | -| Project Number | Enter a specific Project Number to query for associated items | No | -| Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | +| Name | Description | Required | +| ------------- | ----------------------------------------------------------- | -------- | +| Project Owner | One of `Organization` or `User` | Yes | +| Organization | Organization for the Project (shown when Organization was previously selected) | Yes | +| User | User for the Project (shown when User was previously selected) | Yes | +| Project Number | Enter a specific Project Number to query for associated items | No | +| Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | ##### Sample queries Show all projects for the `grafana/grafana` repository: @@ -470,52 +465,51 @@ Show all pull requests for the "Dashboards" project in the Grafana organization: ##### When no Project Number is specified -| Name | Description | -|-------------------|-------------| -| number | The project number | -| title | Title of the project | -| url | URL for the project | -| closed | Whether the project has been closed: `true`/ `false` | -| public | Whether the project is public: `true` / `false` | -| closed_at | When the project was closed: YYYY-MM-DD HH:MM:SS | -| updated_at | When the project was last updated | -| created_at | When the project was created | -| short_description | The description of the project | +| Name | Description | +| ----------------- | ---------------------------------------------------------- | +| number | The project number | +| title | Title of the project | +| url | URL for the project | +| closed | Whether the project has been closed: `true` or `false` | +| public | Whether the project is public: `true` or `false` | +| closed_at | When the project was closed: YYYY-MM-DD HH:MM:SS | +| updated_at | When the project was last updated | +| created_at | When the project was created | +| short_description | The description of the project | ##### When a Project Number is specified {{< admonition type="note" >}} -GitHub Projects allow for customization of default fields and custom fields to be added, -therefore the response can vary significantly between projects." +GitHub Projects allow for customization of default fields and custom fields to be added. Therefore, the response can vary significantly between projects. {{< /admonition >}} -| Name | Description | -|-----------------|-------------| -| name | Name of the project item (issue or pull request) | -| id | Unique identifier for the project item | -| type | Type of the item (such as ISSUE, PULL_REQUEST) | +| Name | Description | +| --------------- | ----------------------------------------------------------- | +| name | Name of the project item (issue or pull request) | +| id | Unique identifier for the project item | +| type | Type of the item (such as `ISSUE`, `PULL_REQUEST`) | | status | Status of the item (such as "In development", "Shipped") - this can be configured on the project | -| labels | Comma-separated list of labels assigned to the item | -| assignees | Comma-separated list of users assigned to the item | -| reviewers | Comma-separated list of reviewers (for pull requests) | -| repository | Name of the repository the item belongs to | -| milestone | Milestone associated with the item | -| priority | Priority value or label | -| archived | Whether the item is archived: `true` / `false` | -| created_at | When the item was created: YYYY-MM-DD HH:MM:SS | -| updated_at | When the item was last updated: YYYY-MM-DD HH:MM:SS | +| labels | Comma-separated list of labels assigned to the item | +| assignees | Comma-separated list of users assigned to the item | +| reviewers | Comma-separated list of reviewers (for pull requests) | +| repository | Name of the repository the item belongs to | +| milestone | Milestone associated with the item | +| priority | Priority value or label | +| archived | Whether the item is archived: `true` or `false` | +| created_at | When the item was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the item was last updated: YYYY-MM-DD HH:MM:SS | | closed_at | When the item was closed, if applicable: YYYY-MM-DD HH:MM:SS | | (custom fields) | Any custom defined fields will also be returned alongside their values | ### Stargazers -Get a list of users who have starred a repository, including being able to plot a total count over time +Get a list of users who have starred a repository, including the ability to plot a total count over time. #### Query options -| Name | Description | Required (yes/no) | -| ------------ | ----------------------------------------------------------| ----------------- | -| Owner | The GitHub user or organization that owns the repository | Yes | -| Repository | The name of the repository | Yes | +| Name | Description | Required | +| ---------- | -------------------------------------------------------- | -------- | +| Owner | The GitHub user or organization that owns the repository | Yes | +| Repository | The name of the repository | Yes | ##### Sample queries Show all stargazers for the `grafana/grafana` repository within the current time range: @@ -523,17 +517,16 @@ Show all stargazers for the `grafana/grafana` repository within the current time - Owner: `grafana` - Repository: `grafana` - #### Response -| Name | Description | -|-------------|-------------| -| starred_at | When the user starred the repository: YYYY-MM-DD HH:MM:SS | +| Name | Description | +| ----------- | ----------------------------------------------------------- | +| starred_at | When the user starred the repository: YYYY-MM-DD HH:MM:SS | | start_count | Current total of stars for the repository at the time of the event | -| id | node_id - a unique identifier for the GitHub user which can be used in GitHub's GraphQL API | -| login | GitHub handle of the user who starred the repository | -| git_name | Name of the GitHub user who starred the repository | -| company | Company name of the GitHub user who starred the repository | +| id | `node_id` - a unique identifier for the GitHub user which can be used in GitHub's GraphQL API | +| login | GitHub handle of the user who starred the repository | +| git_name | Name of the GitHub user who starred the repository | +| company | Company name of the GitHub user who starred the repository | | email | Email address of the GitHub user who starred the repository | | url | URL to the GitHub profile for the user who starred the repository | @@ -543,11 +536,11 @@ List GitHub Actions workflows defined in a repository. #### Query options -| Name | Description | Required (yes/no) | -|------------|-----------------------------------------------------|-------------------| -| owner | GitHub user or organization that owns the repository| Yes | -| repository | Name of the repository | Yes | -| Time Field | The time field to filter the responses on, can be: `CreatedAt` or `UpdatedAt` | Yes | +| Name | Description | Required | +| ---------- | -------------------------------------------------- | -------- | +| owner | GitHub user or organization that owns the repository | Yes | +| repository | Name of the repository | Yes | +| Time Field | The time field to filter the responses on, can be: `CreatedAt` or `UpdatedAt` | Yes | ##### Sample queries Show all workflows created within the `grafana/grafana` repository within the current time range: @@ -556,20 +549,19 @@ Show all workflows created within the `grafana/grafana` repository within the cu - Repository: `grafana` - Time Field: `CreatedAt` - #### Response -| Name | Description | -|------------|-------------| -| id | Unique identifier for the workflow | -| name | Name of the workflow | -| path | Path to the workflow YAML file in the repository | +| Name | Description | +| ---------- | ----------------------------------------------------------- | +| id | Unique identifier for the workflow | +| name | Name of the workflow | +| path | Path to the workflow YAML file in the repository | | state | State of the workflow, can be: `active`, `deleted`, `disabled_fork`, `disabled_inactivity`, or `disabled_manually` | -| created_at | When the workflow was created: YYYY-MM-DD HH:MM:SS | -| updated_at | When the workflow was last updated: YYYY-MM-DD HH:MM:SS | -| url | API URL for the workflow | -| html_url | URL to the workflow file in the repository | -| badge_url | URL to the workflow status badge | +| created_at | When the workflow was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the workflow was last updated: YYYY-MM-DD HH:MM:SS | +| url | API URL for the workflow | +| html_url | URL to the workflow file in the repository | +| badge_url | URL to the workflow status badge | ### Workflow usage @@ -577,12 +569,11 @@ Retrieve usage statistics for a workflow, such as run counts and durations. #### Query options -| Name | Description | Required (yes/no) | -|------------|-----------------------------------------------------|-------------------| -| 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 | - +| 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 | ##### Sample queries Show usage statistics for the `Levitate` detect breaking changes workflow in the `grafana/grafana` repository: @@ -593,27 +584,27 @@ Show usage statistics for the `Levitate` detect breaking changes workflow in the #### Response -| Name | Description | -|-----------------------------|-------------| -| name | Name of the workflow (or workflow job) | -| unique triggering actors | Number of unique users or actors who triggered runs of this workflow | -| runs | Total number of workflow runs in the selected period | -| current billing cycle cost (approx.) | Approximate cost for the current billing cycle (if applicable) | -| skipped | Number (and percentage) of runs that were skipped | -| successes | Number (and percentage) of successful runs | -| failures | Number (and percentage) of failed runs | -| cancelled | Number (and percentage) of cancelled runs | -| total run duration (approx.)| Total duration of all runs (formatted as hours, minutes, seconds) | -| longest run duration (approx.) | Duration of the longest single run | -| average run duration (approx.) | Average duration of all runs | -| p95 run duration (approx.) | 95th percentile run duration | -| runs on Sunday | Number of runs started on Sunday | -| runs on Monday | Number of runs started on Monday | -| runs on Tuesday | Number of runs started on Tuesday | -| runs on Wednesday | Number of runs started on Wednesday | -| runs on Thursday | Number of runs started on Thursday | -| runs on Friday | Number of runs started on Friday | -| runs on Saturday | Number of runs started on Saturday | +| Name | Description | +| --------------------------- | ---------------------------------------------------------------------------- | +| name | Name of the workflow (or workflow job) | +| unique triggering actors | Number of unique users or actors who triggered runs of this workflow | +| runs | Total number of workflow runs in the selected period | +| current billing cycle cost (approx.) | Approximate cost for the current billing cycle (if applicable) | +| skipped | Number (and percentage) of runs that were skipped | +| successes | Number (and percentage) of successful runs | +| failures | Number (and percentage) of failed runs | +| cancelled | Number (and percentage) of cancelled runs | +| total run duration (approx.)| Total duration of all runs (formatted as hours, minutes, seconds) | +| longest run duration (approx.) | Duration of the longest single run | +| average run duration (approx.) | Average duration of all runs | +| p95 run duration (approx.) | 95th percentile run duration | +| runs on Sunday | Number of runs started on Sunday | +| runs on Monday | Number of runs started on Monday | +| runs on Tuesday | Number of runs started on Tuesday | +| runs on Wednesday | Number of runs started on Wednesday | +| runs on Thursday | Number of runs started on Thursday | +| runs on Friday | Number of runs started on Friday | +| runs on Saturday | Number of runs started on Saturday | ### Workflow runs @@ -621,12 +612,12 @@ List runs for a specific workflow, including status, conclusion, and timing info #### Query options -| Name | Description | Required (yes/no) | -|------------|-----------------------------------------------------|-------------------| -| 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 | -| Branch | The head branch to filter on | No | +| 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 | +| Branch | The head branch to filter on | No | ##### Sample queries Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository: @@ -637,18 +628,18 @@ Show all completed runs for the `Levitate` workflow in the `grafana/grafana` rep #### Response -| Name | Description | -|--------------|-------------| -| id | Unique identifier for the workflow run | -| name | Name of the workflow or workflow job | -| head_branch | Name of the branch the workflow run was triggered on | -| head_sha | Commit SHA that triggered the workflow run | -| created_at | When the workflow run was created: YYYY-MM-DD HH:MM:SS | -| updated_at | When the workflow run was last updated: YYYY-MM-DD HH:MM:SS | -| html_url | URL to the workflow run in the GitHub web UI | -| url | API URL for the workflow run | -| status | Current status of the workflow run, can be: `queued`, `in_progress`, `completed`, `waiting`, `requested` or `pending | -| conclusion | Final conclusion of the workflow run, can be `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out` or action_required | -| event | Event that triggered the workflow run (e.g., push, pull_request) - see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) | -| workflow_id | Unique identifier for the workflow definition | -| run_number | The run number for this workflow run in the repository | +| Name | Description | +| ------------ | ------------------------------------------------------------------------ | +| id | Unique identifier for the workflow run | +| name | Name of the workflow or workflow job | +| head_branch | Name of the branch the workflow run was triggered on | +| head_sha | Commit SHA that triggered the workflow run | +| created_at | When the workflow run was created: YYYY-MM-DD HH:MM:SS | +| updated_at | When the workflow run was last updated: YYYY-MM-DD HH:MM:SS | +| html_url | URL to the workflow run in the GitHub web UI | +| url | API URL for the workflow run | +| status | Current status of the workflow run, can be: `queued`, `in_progress`, `completed`, `waiting`, `requested`, or `pending` | +| conclusion | Final conclusion of the workflow run, can be: `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out`, or `action_required` | +| event | Event that triggered the workflow run (e.g., `push`, `pull_request`) - see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) | +| workflow_id | Unique identifier for the workflow definition | +| run_number | The run number for this workflow run in the repository | \ No newline at end of file From a868a2275ecb16de8ad0124f3527e73d772a129e Mon Sep 17 00:00:00 2001 From: David Harris Date: Mon, 16 Jun 2025 14:44:54 +0100 Subject: [PATCH 17/17] apply review comments --- docs/sources/query/_index.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md index 13c657e3..79656b11 100644 --- a/docs/sources/query/_index.md +++ b/docs/sources/query/_index.md @@ -54,6 +54,7 @@ Retrieve a list of commits for a branch or ref within a repository, including co | Ref (Branch/Tag) | The branch or tag to list commits against | Yes | ##### Sample queries + Show all commits to the `main` branch of the `grafana/grafana` repository: - Owner: `grafana` @@ -96,6 +97,7 @@ This query returns a maximum of 1000 results. | Time field | The time field to filter the responses on, can be: `CreatedAt`, `ClosedAt`, or `UpdatedAt` | Yes | ##### Sample queries + Show all closed issues labeled `type/bug` in the Grafana repository: - Owner: `grafana` @@ -140,6 +142,7 @@ This query returns a maximum of 200 results. | Query | Filter for contributors by name or GitHub handle | No | ##### Sample queries + Show all contributors to the `grafana` repository: - Owner: `grafana` @@ -175,6 +178,7 @@ List created tags for a repository. | Repository | The name of the repository | Yes | ##### Sample queries + Show all tags created for the `grafana` repository within the currently selected time range: - Owner: `grafana` @@ -203,6 +207,7 @@ List created releases for a repository. | Repository | The name of the repository | Yes | ##### Sample queries + Show all releases for the `grafana/grafana` repository: - Owner: `grafana` @@ -235,6 +240,7 @@ List pull requests for a repository, using the GitHub query syntax to filter the | Time Field | The time field to filter the responses on, can be: `CreatedAt`, `ClosedAt`, `UpdatedAt`, or `none` | Yes | ##### Sample queries + Show all open pull requests authored by Renovate in the `grafana/plugin-tools` repository: - Owner: `grafana` @@ -280,6 +286,7 @@ Get all labels defined in a repository, useful for categorizing issues and pull | Query | Filter on text in name and description for labels | No | ##### Sample queries + Show all labels for the `grafana/grafana` repository: - Owner: `grafana` @@ -309,6 +316,7 @@ This query returns a maximum of 1000 results. | Repository | Filter on the name of the repository | No | ##### Sample queries + Show all repositories for the `grafana` organization: - Organization: `grafana` @@ -339,6 +347,7 @@ Retrieve milestones for a repository, which can be used to group issues and pull | Query | Filter on text in the milestone title | No | ##### Sample queries + Show all milestones for the `grafana/grafana` repository for v11 of Grafana: - Owner: `grafana` @@ -379,6 +388,7 @@ This query does not support querying npm, RubyGems, or NuGet packages. | Names | Filter for packages using a comma-separated list of names | No | ##### Sample queries + Show all packages uploaded to the `grafana` organization: - Organization: `grafana` @@ -406,6 +416,7 @@ Query security vulnerabilities detected in a repository. | Repository | The name of the repository | Yes | ##### Sample queries + Show all security advisories for the `grafana/grafana` repository: - Owner: `grafana` @@ -449,6 +460,7 @@ This query returns a maximum of 200 results. | Filter | Add key value filters based on the fields for project items (shown if Project Number specified) | No | ##### Sample queries + Show all projects for the `grafana/grafana` repository: - Project Owner: `organization` @@ -512,6 +524,7 @@ Get a list of users who have starred a repository, including the ability to plot | Repository | The name of the repository | Yes | ##### Sample queries + Show all stargazers for the `grafana/grafana` repository within the current time range: - Owner: `grafana` @@ -543,6 +556,7 @@ List GitHub Actions workflows defined in a repository. | Time Field | The time field to filter the responses on, can be: `CreatedAt` or `UpdatedAt` | Yes | ##### Sample queries + Show all workflows created within the `grafana/grafana` repository within the current time range: - Owner: `grafana` @@ -576,6 +590,7 @@ Retrieve usage statistics for a workflow, such as run counts and durations. | Workflow | The workflow ID or file name. Use `id` or the filename from `path` from [workflows](#workflows) queries | Yes | ##### Sample queries + Show usage statistics for the `Levitate` detect breaking changes workflow in the `grafana/grafana` repository: - Owner: `grafana` @@ -620,6 +635,7 @@ List runs for a specific workflow, including status, conclusion, and timing info | Branch | The head branch to filter on | No | ##### Sample queries + Show all completed runs for the `Levitate` workflow in the `grafana/grafana` repository: - Owner: `grafana`