diff --git a/docs/sources/_index.md b/docs/sources/_index.md index cd209f55..2eeb36a2 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -2,6 +2,25 @@ title: GitHub data source plugin for Grafana menuTitle: GitHub data source description: The GitHub data source lets you visualize GitHub data in Grafana dashboards. +hero: + title: Github data source plugin for Grafana + level: 1 + width: 110 + image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg + height: 110 + description: The Github data source plugin allows you to query and visualize data from Github. +query_types: + title_class: pt-0 lh-1 + items: + - title: Repositories + description: List the github repositories for an organization + href: /docs/grafana-github-datasource/latest/query/repositories/ + - title: Issues + description: List the issues created for a github repo + href: /docs/grafana-github-datasource/latest/query/issues/ + - title: Pull Requests + description: List the pull requests created for a github repo + href: /docs/grafana-github-datasource/latest/query/pull-requests/ keywords: - data source - github @@ -15,6 +34,12 @@ labels: weight: 10 --- + + +{{< docs/hero-simple key="hero" >}} + +
+ # GitHub data source plugin for Grafana The GitHub data source plugin for Grafana lets you to query the GitHub API in Grafana so you can visualize your GitHub repositories and projects. @@ -25,16 +50,19 @@ Watch this video to learn more about setting up the Grafana GitHub data source p ## Query types -The plugin supports the following query types: +Grafana Github datasource plugin allows you query various data from github. To know more about supported query types and details, refer the [Query page](/docs/grafana-github-datasource/latest/query/) + +{{< card-grid key="query_types" type="simple" >}} + +### Other query types + +The plugin also supports the following query types: - Commits -- Issues - Contributors - Tags - Releases -- Pull requests - Labels -- Repositories - Milestones - Packages - Vulnerabilities diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 5f5483a4..f684f60b 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -12,7 +12,7 @@ labels: - oss - enterprise - cloud -weight: 400 +weight: 500 --- # Create annotations with GitHub data source plugin for Grafana diff --git a/docs/sources/query/_index.md b/docs/sources/query/_index.md new file mode 100644 index 00000000..d8a2ff47 --- /dev/null +++ b/docs/sources/query/_index.md @@ -0,0 +1,60 @@ +--- +title: 'Query' +menuTitle: Query +description: Query +hero: + title: Github data source plugin for Grafana + level: 1 + width: 110 + image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg + height: 110 + description: The Github data source plugin allows you to query and visualize data from Github. +keywords: + - github + - ci + - cd +query_types: + title_class: pt-0 lh-1 + items: + - title: Repositories + description: List the github repositories for an organization + href: /docs/grafana-github-datasource/latest/query/repositories/ + - title: Issues + description: List the issues created for a github repo + href: /docs/grafana-github-datasource/latest/query/issues/ + - title: Pull Requests + description: List the pull requests created for a github repo + href: /docs/grafana-github-datasource/latest/query/pull-requests/ +labels: + products: + - oss +weight: 300 +--- + + + +{{< docs/hero-simple key="hero" >}} + +
+ +## 🎯 Supported query types + +{{< card-grid key="query_types" type="simple" >}} + +### Other query types + +The plugin also supports the following query types: + +- Commits +- Contributors +- Tags +- Releases +- Labels +- Milestones +- Packages +- Vulnerabilities +- Projects +- Stargazers +- Workflows +- Workflow usage +- Workflow runs diff --git a/docs/sources/query/issues.md b/docs/sources/query/issues.md new file mode 100644 index 00000000..2d89fdc1 --- /dev/null +++ b/docs/sources/query/issues.md @@ -0,0 +1,74 @@ +--- +title: Issues +menuTitle: Issues +description: Issues +hero: + title: List issues + level: 1 + width: 110 + image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg + height: 110 + description: List issues created in a github repo +keywords: + - github + - ci + - cd +labels: + products: + - oss +weight: 302 +--- + + + +{{< docs/hero-simple key="hero" >}} + +
+ +Query type **Issues** allows you to list the issues created in a GitHub repository. + +## Query Parameters + +| Field | Description | Example | +| ---------- | ----------------------------------------------------------------------- | --------- | +| Query Type | Specify the query type as **Issues** | | +| Owner | GitHub user id / organization id | grafana | +| Repository | Name of the repository | grafana | +| Options | **(Optional)**. Additional options such as search query and time field. | See below | + +### Options + +| Field | Description | Example | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | +| **Query** | _(Optional)_ Search string to filter issues. You can use the same syntax as GitHub's search field. | `is:OPEN label:type/bug` | +| **Time Field** | _(Optional)_ Field to use for time filtering (`created`=0, `closed`=1, `updated`=2). If nothing selected, defaults to `created at` and the results will be filtered automatically based on the date.
**Tip**: Grafana's dashboard time range used for these time filters | 0 | + +### Query Schema + +```json +{ + "queryType": "Issues", + "owner": "grafana", + "repository": "grafana", + "options": { + "query": "is:open label:bug", + "timeField": "created" + } +} +``` + +#### Downstream Query + +Under the hood, Grafana uses the following GraphQL query to list the issues: + +```graphql +TBD +``` + +## Result field + +Refer to the [GitHub GraphQL documentation](https://docs.github.com/en/graphql/overview/explorer) for details about all the result fields presented in the GraphQL query. + +## Known Limitations + +- The GitHub plugin paginates over the GraphQL query with a 100 items limit per request. If the repository has a large number of issues, the result might be slower. Use appropriate filters (query, timeField) to improve query performance. diff --git a/docs/sources/query/pull-requests.md b/docs/sources/query/pull-requests.md new file mode 100644 index 00000000..866ee405 --- /dev/null +++ b/docs/sources/query/pull-requests.md @@ -0,0 +1,28 @@ +--- +title: Pull Requests +menuTitle: Pull Requests +description: Pull Request +hero: + title: List pull requests + level: 1 + width: 110 + image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg + height: 110 + description: List pull requests created in a github repo +keywords: + - github + - ci + - cd +labels: + products: + - oss +weight: 302 +--- + + + +{{< docs/hero-simple key="hero" >}} + +
+ +TBD diff --git a/docs/sources/query/repositories.md b/docs/sources/query/repositories.md new file mode 100644 index 00000000..affb7458 --- /dev/null +++ b/docs/sources/query/repositories.md @@ -0,0 +1,82 @@ +--- +title: Repositories +menuTitle: Repositories +description: Repositories +hero: + title: List github repositories + level: 1 + width: 110 + image: https://raw.githubusercontent.com/grafana/github-datasource/refs/heads/main/src/img/github.svg + height: 110 + description: List github repositories for a github organization / user +keywords: + - github + - ci + - cd +labels: + products: + - oss +weight: 301 +--- + + + +{{< docs/hero-simple key="hero" >}} + +
+ +Query type **Repositories** allow you to list the repositories available for a github user/organization + +## Query Parameters + +| Field | Description | Example | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| Query Type | Specify the query type as **Repository** | | +| Owner | Github user id / organization id | grafana | +| Repository | **(Optional)**. Search field. Typically full name of the repository or partial search string.
**Tip**: You can use the same syntax you use in github.com search field | `datasource` / `grafana-infinity-datasource` / `datasources -lang:go`. | + +### Query Schema + +```json +{ + "queryType": "Repositories", + "owner": "grafana", + "repository": "datasource" +} +``` + +#### Downstream Query + +Under the hood, grafana uses the following GraphQL query to list the repositories + +```graphql +{ + search(query: "org:grafana datasource", type: REPOSITORY, first: 100) { + nodes { + ... on Repository { + name + owner { + login + } + nameWithOwner + url + forks { + totalCount + } + isFork + isMirror + isPrivate + createdAt + } + } + } +} +``` + +## Result field + +Refer the [Github GraphQL documentation](https://docs.github.com/en/graphql/overview/explorer) for the details about all the result fields presented in the GraphQL query. + +## Known Limitations + +- Github plugin does pagination over the graphQL query with 100 pages limit on each request. If the owner/user have more number of repositories, then there are potential chances that the result might be slower. Use appropriate search filer in the repository field to increase the query performance. diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index edc33ee2..444e8c8a 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: 400 --- # Use GitHub data source variables and macros in Grafana diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index ebee6ee4..5b943452 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: 402 --- # 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..c1199fe5 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: 401 --- # Create variable with GitHub data source plugin for Grafana diff --git a/docs/variables.mk b/docs/variables.mk index 727ed7da..7b4b7d61 100644 --- a/docs/variables.mk +++ b/docs/variables.mk @@ -1 +1 @@ -PROJECTS := github-datasource +PROJECTS := grafana-github-datasource