From c8677e2759f18c054f0472b766698d589c0c3534 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 4 Mar 2024 13:05:54 +0100 Subject: [PATCH 01/61] created docs folder structure --- docs/sources/_index.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 docs/sources/_index.md diff --git a/docs/sources/_index.md b/docs/sources/_index.md new file mode 100644 index 00000000..b3791f26 --- /dev/null +++ b/docs/sources/_index.md @@ -0,0 +1,17 @@ +title: GitHub data source plugin for Grafana +menuTitle: GitHub data source +description: This document introduces the GitHub data source +aliases: + - github +keywords: + - data source + - github + - github repository + - api +labels: + products: + - oss + - enterprise + - grafana cloud +weight: 10 +--- From 56a89d2d2d991b20ca73cef05b6d2fe0031ec409 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 8 May 2024 16:30:05 +0200 Subject: [PATCH 02/61] created the basic doc structure --- docs/sources/_index.md | 59 +++++++++++++++++++++++++++++ docs/sources/annotations/_index.md | 19 ++++++++++ docs/sources/examples/index.md | 0 docs/sources/setup/configuration.md | 0 docs/sources/setup/installation.md | 0 docs/sources/setup/provisioning.md | 0 6 files changed, 78 insertions(+) create mode 100644 docs/sources/annotations/_index.md create mode 100644 docs/sources/examples/index.md create mode 100644 docs/sources/setup/configuration.md create mode 100644 docs/sources/setup/installation.md create mode 100644 docs/sources/setup/provisioning.md diff --git a/docs/sources/_index.md b/docs/sources/_index.md index b3791f26..b82c3aa3 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -15,3 +15,62 @@ labels: - grafana cloud weight: 10 --- + +# Overview + +The GitHub datasource allows GitHub API data to be visually represented in Grafana dashboards. + +## GitHub API V4 (GraphQL) + +This datasource uses the [`githubv4` package](https://github.com/shurcooL/githubv4), which is under active development. + +## Key Features + +### Backend + +- [x] Releases +- [x] Commits +- [x] Repositories +- [x] Stargazers +- [x] Issues +- [x] Organizations +- [x] Labels +- [x] Milestones +- [x] Response Caching +- [x] Projects +- [x] Workflows +- [ ] Deploys + +### Frontend + +- [x] Visualize queries +- [x] Template variables +- [x] Annotations + +### Caching + +Caching on this plugin is always enabled. + + +## Frequently Asked Questions + +- **I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared `access_token`?** + +No. This requires changes in Grafana first. See [this issue](https://github.com/grafana/grafana/issues/26023) in the Grafana project. + +- **Why does it sometimes take up to 5 minutes for my new pull request / new issue / new commit to show up?** + +We have aggressive caching enabled due to GitHub's rate limiting policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily. + +- **Why are there two selection options for Pull Requests and Issue times when creating annotations?** + +There are two times that affect an annotation: + +- The time range of the dashboard or panel +- The time that should be used to display the event on the graph + +The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. + +The second selection is used to determine where on the graph the event should be displayed. + +Typically these will be the same, however there are some cases where you may want them to be different. \ No newline at end of file diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md new file mode 100644 index 00000000..1d0b2107 --- /dev/null +++ b/docs/sources/annotations/_index.md @@ -0,0 +1,19 @@ +## Annotations + +Annotations overlay events on a graph. + +![Annotations on a graph](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/annotations.png) + +With annotations, you can display: + +- Commits +- Issues +- Pull Requests +- Releases +- Tags + +on a graph. + +All annotations require that you select a field to display on the annotation, and a field that represents the time that the event occurred. + +![Annotations editor](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/annotations-editor.png) \ No newline at end of file diff --git a/docs/sources/examples/index.md b/docs/sources/examples/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md new file mode 100644 index 00000000..e69de29b From 15a8b3d948a71d2b461a9f7408e14cce49006d5e Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 8 May 2024 16:45:13 +0200 Subject: [PATCH 03/61] added more docs --- docs/sources/_index.md | 2 ++ docs/sources/variables-and-macros/_index.md | 0 2 files changed, 2 insertions(+) create mode 100644 docs/sources/variables-and-macros/_index.md diff --git a/docs/sources/_index.md b/docs/sources/_index.md index b82c3aa3..3aae5675 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -20,6 +20,8 @@ weight: 10 The GitHub datasource allows GitHub API data to be visually represented in Grafana dashboards. +{{< docs/play title="Infinity plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} + ## GitHub API V4 (GraphQL) This datasource uses the [`githubv4` package](https://github.com/shurcooL/githubv4), which is under active development. diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md new file mode 100644 index 00000000..e69de29b From 326da394318bfedb2182b832060540bcc7ed3f0c Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 8 May 2024 17:19:11 +0200 Subject: [PATCH 04/61] saved changes --- docs/sources/examples/index.md | 13 +++++++++++++ docs/sources/setup/configuration.md | 19 +++++++++++++++++++ docs/sources/setup/provisioning.md | 17 +++++++++++++++++ docs/sources/variables-and-macros/_index.md | 19 +++++++++++++++++++ 4 files changed, 68 insertions(+) diff --git a/docs/sources/examples/index.md b/docs/sources/examples/index.md index e69de29b..909a0124 100644 --- a/docs/sources/examples/index.md +++ b/docs/sources/examples/index.md @@ -0,0 +1,13 @@ +## Sample Dashboard + +For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) + +The sample dashboard can be obtained from either of two places. + +1. From the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) + +2. From the official [repository](https://github.com/grafana/github-datasource/) + +If loading it from the official repository, open Grafana and click "Import Dashboard". + +Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index e69de29b..3f3ac62c 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -0,0 +1,19 @@ +## Access Token Permissions + +For all repositories: + +- `public_repo` +- `repo:status` +- `repo_deployment` +- `read:packages` +- `read:user` +- `user:email` + +For Github projects: + +- `read:org` +- `read:project` + +An extra setting is required for private repositories + +- `repo (Full control of private repositories)` \ No newline at end of file diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index e69de29b..ffc9a477 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -0,0 +1,17 @@ +### Provisioning + +[It’s possible to configure data sources using config files with Grafana’s provisioning system](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). + +#### With the [prom-operator](https://github.com/prometheus-operator/prometheus-operator) + +```yaml +promop: + grafana: + additionalDataSources: + - name: GitHub Repo Insights + type: grafana-github-datasource + jsonData: + owner: '' + repository: '' + secureJsonData: + accessToken: '' \ 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 e69de29b..1e5bbc96 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -0,0 +1,19 @@ +## Variables + +[Variables](https://grafana.com/docs/grafana/latest/variables/) allow you to substitute values in a panel with pre-defined values. + +![Creating Variables](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/variables-create.png) + +You can reference them inside queries, allowing users to configure parameters such as `Query` or `Repository`. + +![Using Variables inside queries](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/using-variables.png) + +## Macros + +You can use the following macros in your queries + +| Macro Name | Syntax | Description | Example | +| ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | +| multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | +| | | When using **all** in multi variable, use **\*** as custom all value | | +| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | \ No newline at end of file From 08714045bcb4fe5f0e52cf6e75b380a39be45ade Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Wed, 29 May 2024 14:11:55 +0100 Subject: [PATCH 05/61] Add `make docs` procedure and a workflow to keep it up to date Signed-off-by: Jack Baldry (cherry picked from commit 9f857e7666116c045e6f4cf37f5864788959aaff) Signed-off-by: Jack Baldry --- .github/CODEOWNERS | 7 + .github/workflows/update-make-docs.yml | 15 + docs/Makefile | 8 + docs/docs.mk | 122 ++++ docs/make-docs | 911 +++++++++++++++++++++++++ docs/sources/_index.md | 14 +- docs/variables.mk | 1 + 7 files changed, 1070 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/update-make-docs.yml create mode 100644 docs/Makefile create mode 100644 docs/docs.mk create mode 100755 docs/make-docs create mode 100644 docs/variables.mk diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 96f534cd..bb42d23f 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -4,3 +4,10 @@ # The '*' pattern is global owners. * @grafana/oss-big-tent + +docs/docs.mk @jdbaldry +docs/make-docs @jdbaldry +docs/Makefile @jdbaldry +docs/variables.mk @jdbaldry + +.github/workflows/update-make-docs.yml @jdbaldry \ No newline at end of file diff --git a/.github/workflows/update-make-docs.yml b/.github/workflows/update-make-docs.yml new file mode 100644 index 00000000..347ef3e8 --- /dev/null +++ b/.github/workflows/update-make-docs.yml @@ -0,0 +1,15 @@ +name: Update `make docs` procedure +on: + schedule: + - cron: '0 7 * * 1-5' + workflow_dispatch: +jobs: + main: + if: github.repository == 'grafana/github-datasource' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: grafana/writers-toolkit/update-make-docs@update-make-docs/v1 + with: + pr_options: > + --label type/docs diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..2eaab546 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,8 @@ +.ONESHELL: +.DELETE_ON_ERROR: +export SHELL := bash +export SHELLOPTS := pipefail:errexit +MAKEFLAGS += --warn-undefined-variables +MAKEFLAGS += --no-builtin-rule + +include docs.mk diff --git a/docs/docs.mk b/docs/docs.mk new file mode 100644 index 00000000..c0aae10b --- /dev/null +++ b/docs/docs.mk @@ -0,0 +1,122 @@ +# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk. +# A changelog is included in the head of the `make-docs` script. +include variables.mk +-include variables.mk.local + +.ONESHELL: +.DELETE_ON_ERROR: +export SHELL := bash +export SHELLOPTS := pipefail:errexit +MAKEFLAGS += --warn-undefined-variables +MAKEFLAGS += --no-builtin-rule + +.DEFAULT_GOAL: help + +# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/ +.PHONY: help +help: ## Display this help. +help: + @awk 'BEGIN { \ + FS = ": ##"; \ + printf "Usage:\n make \n\nTargets:\n" \ + } \ + /^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf " %-15s %s\n", $$1, $$2 }' \ + $(MAKEFILE_LIST) + +GIT_ROOT := $(shell git rev-parse --show-toplevel) + +PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi) + +ifeq ($(PROJECTS),) +$(error "PROJECTS variable must be defined in variables.mk") +endif + +# First project is considered the primary one used for doc-validator. +PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS))))) + +# Host port to publish container port to. +ifeq ($(origin DOCS_HOST_PORT), undefined) +export DOCS_HOST_PORT := 3002 +endif + +# Container image used to perform Hugo build. +ifeq ($(origin DOCS_IMAGE), undefined) +export DOCS_IMAGE := grafana/docs-base:latest +endif + +# Container image used for doc-validator linting. +ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined) +export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest +endif + +# Container image used for vale linting. +ifeq ($(origin VALE_IMAGE), undefined) +export VALE_IMAGE := grafana/vale:latest +endif + +# PATH-like list of directories within which to find projects. +# If all projects are checked out into the same directory, ~/repos/ for example, then the default should work. +ifeq ($(origin REPOS_PATH), undefined) +export REPOS_PATH := $(realpath $(GIT_ROOT)/..) +endif + +# How to treat Hugo relref errors. +ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined) +export HUGO_REFLINKSERRORLEVEL := WARNING +endif + +# Whether to pull the latest container image before running the container. +ifeq ($(origin PULL), undefined) +export PULL := true +endif + +.PHONY: docs-rm +docs-rm: ## Remove the docs container. + $(PODMAN) rm -f $(DOCS_CONTAINER) + +.PHONY: docs-pull +docs-pull: ## Pull documentation base image. + $(PODMAN) pull -q $(DOCS_IMAGE) + +make-docs: ## Fetch the latest make-docs script. +make-docs: + if [[ ! -f "$(CURDIR)/make-docs" ]]; then + echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2 + exit 1 + fi + +.PHONY: docs +docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. To not pull the image, set `PULL=false`. +ifeq ($(PULL), true) +docs: docs-pull make-docs +else +docs: make-docs +endif + $(CURDIR)/make-docs $(PROJECTS) + +.PHONY: docs-debug +docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile. +docs-debug: make-docs + WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(CURDIR)/make-docs $(PROJECTS) + +.PHONY: doc-validator +doc-validator: ## Run doc-validator on the entire docs folder which includes pulling the latest `DOC_VALIDATOR_IMAGE` (default: `grafana/doc-validator:latest`) container image. To not pull the image, set `PULL=false`. +doc-validator: make-docs +ifeq ($(PULL), true) + $(PODMAN) pull -q $(DOC_VALIDATOR_IMAGE) +endif + DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(CURDIR)/make-docs $(PROJECTS) + +.PHONY: vale +vale: ## Run vale on the entire docs folder which includes pulling the latest `VALE_IMAGE` (default: `grafana/vale:latest`) container image. To not pull the image, set `PULL=false`. +vale: make-docs +ifeq ($(PULL), true) + $(PODMAN) pull -q $(VALE_IMAGE) +endif + DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS) + +.PHONY: update +update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit. + curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk + curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs + chmod +x make-docs diff --git a/docs/make-docs b/docs/make-docs new file mode 100755 index 00000000..f531df2e --- /dev/null +++ b/docs/make-docs @@ -0,0 +1,911 @@ +#!/bin/sh +# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs. +# # `make-docs` procedure changelog +# +# Updates should conform to the guidelines in https://keepachangelog.com/en/1.1.0/. +# [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes. +# Changes are relevant to this script and the support docs.mk GNU Make interface. +# +# ## 8.0.0 (2024-05-28) +# +# ### Changed +# +# - Add environment variable `OUTPUT_FORMAT` to control the output of commands. +# +# The default value is `human` and means the output format is human readable. +# The value `json` is also supported and outputs JSON. +# +# Note that the `json` format isn't supported by `make docs`, only `make doc-validator` and `make vale`. +# +# ## 7.0.0 (2024-05-03) +# +# ### Changed +# +# - Pull images for all recipes that use containers by default. +# +# Use the `PULL=false` variable to disable this behavior. +# +# ### Removed +# +# - The `docs-no-pull` target as it's redundant with the new `PULL=false` variable. +# +# ## 6.1.0 (2024-04-22) +# +# ### Changed +# +# - Mount volumes with SELinux labels. +# +# https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label +# +# ### Added +# +# - Pseudo project for including only website resources and no website content. +# +# Facilitates testing shortcodes and layout changes with a small documentation set instead of Grafana Cloud or the entire website. +# +# ## 6.0.1 (2024-02-28) +# +# ### Added +# +# - Suppress new errors relating to absent content introduced in https://github.com/grafana/website/pull/17561. +# +# ## 6.0.0 (2024-02-16) +# +# ### Changed +# +# - Require `jq` for human readable `make doc-validator` output. +# +# ## 5.4.0 (2024-02-12) +# +# ### Changed +# +# - Set `WEBSITE_MOUNTS=true` when a user includes the `website` project. +# +# Ensures consistent behavior across repositories. +# To disable website mounts, add `export WEBSITE_MOUNTS := false` to your `variables.mk` or `variables.mk.local` file. +# - Use website mounts and container volumes also when a user includes the `grafana-cloud` project. +# +# ## 5.3.0 (2024-02-08) +# +# ### Changed +# +# - Updated support for plugins monorepo now that multiple projects have been moved into it. +# - Use `printf` instead of `echo` for better portability of output. +# +# https://www.in-ulm.de/~mascheck/various/echo+printf/ +# +# ## 5.2.0 (2024-01-18) +# +# ### Changed +# +# - Updated `make vale` to use latest Vale style and configuration. +# - Updated `make vale` to use platform appropriate image. +# +# ## 5.1.2 (2023-11-08) +# +# ### Added +# +# - Hide manual_mount warning messages from non-debug output. +# Set the DEBUG environment variable to see all hidden messages. +# +# ## 5.1.1 (2023-10-30) +# +# ### Added +# +# - Support for Datadog and Oracle data source plugins repositories. +# +# ## 5.1.0 (2023-10-20) +# +# ### Added +# +# - Support for the plugins monorepo. +# +# ## 5.0.0 (2023-10-18) +# +# ### Added +# +# - Improved support for website repository. +# +# Mount more content and provide some feedback to users that the build can take time. +# +# - Ability to enter the `grafana/docs-base` container with a shell using the `ENTER` environment variable. +# +# ### Fixed +# +# - Correct key combination for interrupting the process. +# +# Keyboards use capital letters so this more accurately reflects the exact key combination users are expected to press. +# +# ### Removed +# +# - Imperfect implementation of container name. +# +# Facilitates running `make vale` and `make docs` at once. +# Container names are convenient for recognition in `docker ps` but the current implementation has more downsides than upsides. +# +# - Forced platform specification now that multiple architecture images exist. +# +# Significantly speeds up build times on larger repositories. +# +# ## 4.2.2 (2023-10-05) + +# - Added support for Jira data source and MongoDB data source plugins repositories. +# +# ## 4.2.1 (2023-09-13) + +# ## Fixed +# +# - Improved consistency of the webserver request loop by polling the Hugo port rather than the proxy port. +# +# ## 4.2.0 (2023-09-01) +# +# ### Added +# +# - Retry the initial webserver request up to ten times to allow for the process to start. +# If it is still failing after ten seconds, an error message is logged. +# +# ## 4.1.1 (2023-07-20) +# +# ### Fixed +# +# - Replaced use of `realpath` with POSIX compatible alternative to determine default value for REPOS_PATH. +# +# ## 4.1.0 (2023-06-16) +# +# ### Added +# +# - Mounts of `layouts` and `config` directories for the `website` project. +# Ensures that local changes to mounts or shortcodes are reflected in the development server. +# +# ### Fixed +# +# - Version inference for versioned docs pages. +# Pages in versioned projects now have the `versioned: true` front matter set to ensure that "version" in $.Page.Scratch is set on builds. +# +# ## 4.0.0 (2023-06-06) +# +# ### Removed +# +# - `doc-validator/%` target. +# The behavior of the target was not as described. +# Instead, to limit `doc-validator` to only specific files, refer to https://grafana.com/docs/writers-toolkit/writing-guide/tooling-and-workflows/validate-technical-documentation/#run-on-specific-files. +# +# ## 3.0.0 (2023-05-18) +# +# ### Fixed +# +# - Compatibility with the updated Make targets in the `website` repository. +# `docs` now runs this script itself, `server-docs` builds the site with the `docs` Hugo environment. +# +# ## 2.0.0 (2023-05-18) +# +# ### Added +# +# - Support for the grafana-cloud/frontend-observability/faro-web-sdk project. +# - Use of `doc-validator` v2.0.x which includes breaking changes to command line options. +# +# ### Fixed +# +# - Source grafana-cloud project from website repository. +# +# ### Added +# +# - Support for running the Vale linter with `make vale`. +# +# ## 1.2.1 (2023-05-05) +# +# ### Fixed +# +# - Use `latest` tag of `grafana/vale` image by default instead of hardcoded older version. +# - Fix mounting multiple projects broken by the changes in 1.0.1 +# +# ## 1.2.0 (2023-05-05) +# +# ### Added +# +# - Support for running the Vale linter with `make vale`. +# +# ### Fixed +# +# ## 1.1.0 (2023-05-05) +# +# ### Added +# +# - Rewrite error output so it can be followed by text editors. +# +# ### Fixed +# +# - Fix `docs-debug` container process port. +# +# ## 1.0.1 (2023-05-04) +# +# ### Fixed +# +# - Ensure complete section hierarchy so that all projects have a visible menu. +# +# ## 1.0.0 (2023-05-04) +# +# ### Added +# +# - Build multiple projects simultaneously if all projects are checked out locally. +# - Run [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) over projects. +# - Redirect project root to mounted version. +# For example redirect `/docs/grafana/` to `/docs/grafana/latest/`. +# - Support for Podman or Docker containers with `PODMAN` environment variable. +# - Support for projects: +# - agent +# - enterprise-logs +# - enterprise-metrics +# - enterprise-traces +# - grafana +# - grafana-cloud +# - grafana-cloud/machine-learning +# - helm-charts/mimir-distributed +# - helm-charts/tempo-distributed +# - incident +# - loki +# - mimir +# - oncall +# - opentelemetry +# - phlare +# - plugins +# - slo +# - tempo +# - writers-toolkit + + +set -ef + +readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}" +readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}" + +readonly DOC_VALIDATOR_INCLUDE="${DOC_VALIDATOR_INCLUDE:-.+\.md$}" +readonly DOC_VALIDATOR_SKIP_CHECKS="${DOC_VALIDATOR_SKIP_CHECKS:-^image-}" + +readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}" +readonly VALE_MINALERTLEVEL="${VALE_MINALERTLEVEL:-error}" +readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server-docs}" + +readonly OUTPUT_FORMAT="${OUTPUT_FORMAT:-human}" + +PODMAN="$(if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)" + +if ! command -v curl >/dev/null 2>&1; then + if ! command -v wget >/dev/null 2>&1; then + errr 'either `curl` or `wget` must be installed for this script to work.' + + exit 1 + fi +fi + +if ! command -v "${PODMAN}" >/dev/null 2>&1; then + errr 'either `podman` or `docker` must be installed for this script to work.' + + exit 1 +fi + + +about() { + cat <...]> $0 [[:[:[:]]]...] + +Examples: + REPOS_PATH=~/ext/grafana/ $0 writers-toolkit tempo:latest helm-charts/mimir-distributed:latest:mimir:docs/sources/mimir-distributed +EOF +} + +if [ $# -lt 1 ]; then + cat <&2 +ERRR: arguments required but not supplied. + +$(about) + +$(usage) +EOF + exit 1 +fi + +readonly REPOS_PATH="${REPOS_PATH:-$(cd "$(git rev-parse --show-toplevel)/.." && echo "${PWD}")}" + +if [ -z "${REPOS_PATH}" ]; then + cat <&2 +ERRR: REPOS_PATH environment variable is required but has not been provided. + +$(usage) +EOF + exit 1 +fi + +SOURCES_as_code='as-code-docs' +SOURCES_enterprise_metrics='backend-enterprise' +SOURCES_enterprise_metrics_='backend-enterprise' +SOURCES_grafana_cloud='website' +SOURCES_grafana_cloud_alerting_and_irm_machine_learning='machine-learning' +SOURCES_grafana_cloud_alerting_and_irm_slo='slo' +SOURCES_grafana_cloud_k6='k6-docs' +SOURCES_grafana_cloud_data_configuration_integrations='cloud-onboarding' +SOURCES_grafana_cloud_frontend_observability_faro_web_sdk='faro-web-sdk' +SOURCES_helm_charts_mimir_distributed='mimir' +SOURCES_helm_charts_tempo_distributed='tempo' +SOURCES_opentelemetry='opentelemetry-docs' +SOURCES_plugins_grafana_datadog_datasource='datadog-datasource' +SOURCES_plugins_grafana_oracle_datasource='oracle-datasource' +SOURCES_resources='website' + +VERSIONS_as_code='UNVERSIONED' +VERSIONS_grafana_cloud='UNVERSIONED' +VERSIONS_grafana_cloud_alerting_and_irm_machine_learning='UNVERSIONED' +VERSIONS_grafana_cloud_alerting_and_irm_slo='UNVERSIONED' +VERSIONS_grafana_cloud_k6='UNVERSIONED' +VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED' +VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED' +VERSIONS_opentelemetry='UNVERSIONED' +VERSIONS_plugins_grafana_datadog_datasource='latest' +VERSIONS_plugins_grafana_oracle_datasource='latest' +VERSIONS_resources='UNVERSIONED' +VERSIONS_technical_documentation='UNVERSIONED' +VERSIONS_website='UNVERSIONED' +VERSIONS_writers_toolkit='UNVERSIONED' + +PATHS_grafana_cloud='content/docs/grafana-cloud' +PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed' +PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed' +PATHS_mimir='docs/sources/mimir' +PATHS_plugins_grafana_datadog_datasource='docs/sources' +PATHS_plugins_grafana_oracle_datasource='docs/sources' +PATHS_resources='content' +PATHS_tempo='docs/sources/tempo' +PATHS_website='content' + +# identifier STR +# Replace characters that are not valid in an identifier with underscores. +identifier() { + echo "$1" | tr -C '[:alnum:]_\n' '_' +} + +# aget ARRAY KEY +# Get the value of KEY from associative array ARRAY. +# Characters that are not valid in an identifier are replaced with underscores. +aget() { + eval echo '$'"$(identifier "$1")_$(identifier "$2")" +} + +# src returns the project source repository name for a project. +src() { + _project="$1" + + case "${_project}" in + plugins/*) + if [ -z "$(aget SOURCES "${_project}")" ]; then + echo plugins-private + else + aget SOURCES "${_project}" + fi + ;; + *) + if [ -z "$(aget SOURCES "${_project}")" ]; then + echo "${_project}" + else + aget SOURCES "${_project}" + fi + ;; + esac + + unset _project +} + +# path returns the relative path within the repository that contain the docs for a project. +path() { + _project="$1" + + case "${_project}" in + plugins/*) + if [ -z "$(aget PATHS "${_project}")" ]; then + echo "${_project}/docs/sources" + else + aget PATHS "${_project}" + fi + ;; + *) + if [ -z "$(aget PATHS "${_project}")" ]; then + echo "docs/sources" + else + aget PATHS "${_project}" + fi + esac + + unset _project +} + +# version returns the version for a project. Unversioned projects return the special value 'UNVERSIONED'. +version() { + _project="$1" + + case "${_project}" in + plugins/*) + if [ -z "$(aget VERSIONS "${_project}")" ]; then + echo "UNVERSIONED" + else + aget VERSIONS "${_project}" + fi + ;; + *) + if [ -z "$(aget VERSIONS "${_project}")" ]; then + echo latest + else + aget VERSIONS "${_project}" + fi + esac + + unset _project +} + + +# new_proj populates a new project structure. +new_proj() { + _project="$1" + _version="$2" + _repo="$3" + _path="$4" + + # If version is not set, use the script mapping of project to default versions if it exists. + # Fallback to 'latest'. + if [ -z "${_version}" ]; then + _version="$(version "${_project}")" + fi + + # If repo is not set, use the script mapping of project to repo name if it exists. + # Fallback to using the project name. + if [ -z "${_repo}" ]; then + _repo="$(src "${_project}")" + fi + + # If path is not set, use the script mapping of project to docs sources path if it exists. + # Fallback to using 'docs/sources'. + if [ -z "${_path}" ]; then + _path="$(path "${_project}")" + fi + + echo "${_project}:${_version}:${_repo}:${_path}" + unset _project _version _repo _path +} + +# proj_url returns the webserver URL for a project. +# It expects a complete project structure as input. +proj_url() { + IFS=: read -r _project _version _ _ <&2 + fi +} + +errr() { + printf 'ERRR: %s\r\n' "$1" >&2 +} + +note() { + printf 'NOTE: %s\r\n' "$1" >&2 +} + +url_src_dst_vers="$(url_src_dst_vers "$@")" + +volumes="" +redirects="" + +for arg in "$@"; do + IFS=: read -r _project _ _repo _ </dev/null 2>&1; then + errr '`jq` must be installed for the `doc-validator` target to work.' + note 'To install `jq`, refer to https://jqlang.github.io/jq/download/,' + + exit 1 + fi + + ${cmd} \ + | jq -r '"ERROR: \(.location.path):\(.location.range.start.line // 1):\(.location.range.start.column // 1): \(.message)" + if .suggestions[0].text then "\nSuggestion: \(.suggestions[0].text)" else "" end' + ;; + json) + ${cmd} + ;; + *) # default + errr "Invalid output format '${OUTPUT_FORMAT}'" + esac + ;; + 'grafana/vale') + proj="$(new_proj "$1")" + printf '\r\n' + IFS='' read -r cmd <"${tempfile}" +#!/usr/bin/env bash + +tc() { + set \${*,,} + echo \${*^} +} + +for redirect in ${redirects}; do + IFS='^' read -r path ver <<<"\${redirect}" + echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}" +done + +for x in "${url_src_dst_vers}"; do + IFS='^' read -r _ _ dst _ <<<"\${x}" + + title="\${dst%/*}" + title="\$(tc \${title##*/})" + while [[ -n "\${dst}" ]]; do + if [[ ! -f "\${dst}/_index.md" ]]; then + echo -e "---title: \${title}\\n---\\n\\n# \${title}\\n\\n{{< section >}}" > "\${dst}/_index.md" + fi + dst="\${dst%/*}" + done +done + +if [[ -n "${WEBSITE_MOUNTS}" ]]; then + unset WEBSITE_SKIP_MOUNTS +fi + +${WEBSITE_EXEC} +EOF + chmod +x "${tempfile}" + volumes="${volumes} --volume=${tempfile}:/entrypoint:z" + readonly volumes + + IFS='' read -r cmd <&1\ + | sed -u \ + -e '/Web Server is available at http:\/\/localhost:3003\/ (bind address 0.0.0.0)/ d' \ + -e '/^hugo server/ d' \ + -e '/fatal: not a git repository (or any parent up to mount point \/)/ d' \ + -e '/Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set)./ d' \ + -e "/Makefile:[0-9]*: warning: overriding recipe for target 'docs'/ d" \ + -e "/docs.mk:[0-9]*: warning: ignoring old recipe for target 'docs'/ d" \ + -e '/\/usr\/bin\/make -j 2 proxy hserver-docs HUGO_PORT=3003/ d' \ + -e '/website-proxy/ d' \ + -e '/rm -rf dist*/ d' \ + -e '/Press Ctrl+C to stop/ d' \ + -e '/make/ d' \ + -e '/WARNING: The manual_mount source directory/ d' \ + -e '/docs\/_index.md .* not found/ d' + fi + ;; +esac diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 3aae5675..42617845 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -1,18 +1,17 @@ -title: GitHub data source plugin for Grafana -menuTitle: GitHub data source -description: This document introduces the GitHub data source -aliases: - - github +--- +description: The GitHub data source lets you visualize GitHub API data in Grafana dashboards. keywords: - data source - github - github repository - - api + - API labels: products: - oss - enterprise - grafana cloud +menuTitle: GitHub data source +title: GitHub data source plugin for Grafana weight: 10 --- @@ -53,7 +52,6 @@ This datasource uses the [`githubv4` package](https://github.com/shurcooL/github Caching on this plugin is always enabled. - ## Frequently Asked Questions - **I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared `access_token`?** @@ -75,4 +73,4 @@ The first selection is used to filter the events that display on the graph. For The second selection is used to determine where on the graph the event should be displayed. -Typically these will be the same, however there are some cases where you may want them to be different. \ No newline at end of file +Typically these will be the same, however there are some cases where you may want them to be different. diff --git a/docs/variables.mk b/docs/variables.mk new file mode 100644 index 00000000..727ed7da --- /dev/null +++ b/docs/variables.mk @@ -0,0 +1 @@ +PROJECTS := github-datasource From bd4ced56af980d6b814d11fff1b770dfcdf4fa7c Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 2 Jul 2024 18:28:21 +0200 Subject: [PATCH 06/61] added new info --- docs/sources/_index.md | 4 +++- docs/sources/examples/index.md | 17 +++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 42617845..023ebbf1 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -19,7 +19,7 @@ weight: 10 The GitHub datasource allows GitHub API data to be visually represented in Grafana dashboards. -{{< docs/play title="Infinity plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} +{{< docs/play title="GitHub Data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} ## GitHub API V4 (GraphQL) @@ -27,6 +27,8 @@ This datasource uses the [`githubv4` package](https://github.com/shurcooL/github ## Key Features +The Grafana GitHub Data source plugin provides several features, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. + ### Backend - [x] Releases diff --git a/docs/sources/examples/index.md b/docs/sources/examples/index.md index 909a0124..8c7f86d9 100644 --- a/docs/sources/examples/index.md +++ b/docs/sources/examples/index.md @@ -1,3 +1,20 @@ +--- +description: The GitHub data source lets you visualize GitHub API data in Grafana dashboards. +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - grafana cloud +menuTitle: GitHub data source +title: GitHub data source plugin for Grafana +weight: 10 +--- + ## Sample Dashboard For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) From d52849f17775718fb6c66a6d697b006fadf1dca7 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 3 Jul 2024 11:30:39 +0200 Subject: [PATCH 07/61] made more sections --- docs/sources/_index.md | 27 +++----------- docs/sources/examples/_index.md | 42 +++++++++++++++++++++ docs/sources/examples/index.md | 30 --------------- docs/sources/faq/_index.md | 41 ++++++++++++++++++++ docs/sources/report-issues/_index.md | 22 +++++++++++ docs/sources/setup/_index.md | 25 +++++++++++++ docs/sources/setup/installation.md | 56 ++++++++++++++++++++++++++++ 7 files changed, 192 insertions(+), 51 deletions(-) create mode 100644 docs/sources/examples/_index.md delete mode 100644 docs/sources/examples/index.md create mode 100644 docs/sources/faq/_index.md create mode 100644 docs/sources/report-issues/_index.md create mode 100644 docs/sources/setup/_index.md diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 023ebbf1..dc5a158b 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -9,7 +9,7 @@ labels: products: - oss - enterprise - - grafana cloud + - cloud menuTitle: GitHub data source title: GitHub data source plugin for Grafana weight: 10 @@ -54,25 +54,10 @@ The Grafana GitHub Data source plugin provides several features, allow you to tr Caching on this plugin is always enabled. -## Frequently Asked Questions +## Requirements -- **I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared `access_token`?** +The GitHub data source plugin has the following requirements: -No. This requires changes in Grafana first. See [this issue](https://github.com/grafana/grafana/issues/26023) in the Grafana project. - -- **Why does it sometimes take up to 5 minutes for my new pull request / new issue / new commit to show up?** - -We have aggressive caching enabled due to GitHub's rate limiting policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily. - -- **Why are there two selection options for Pull Requests and Issue times when creating annotations?** - -There are two times that affect an annotation: - -- The time range of the dashboard or panel -- The time that should be used to display the event on the graph - -The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. - -The second selection is used to determine where on the graph the event should be displayed. - -Typically these will be the same, however there are some cases where you may want them to be different. +- A GitHub account. +- Any free or paid Grafana Cloud plan or an activated on-prem Grafana Enterprise license. Contracted Cloud customers should refer to their agreement. +- Port 3000 enabled. diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md new file mode 100644 index 00000000..fcc26997 --- /dev/null +++ b/docs/sources/examples/_index.md @@ -0,0 +1,42 @@ +--- +title: 'Examples' +menuTitle: Examples +description: Examples +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 500 +--- + +# Example Dashboard + +Here are some examples dashboards that you can use for your usecase. + +## Pre-configure Dashboards + +For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard). + +The sample dashboard can be obtained from either of two places. + +1. Importing from the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) +1. From the Grafana Web UI: + 1. Navigate to Connections and then click Data sources. + 1. Select the GitHub plugin and click the Dashboards tab. + 1. Click Import. + + {{% admonition type="note" %}} + If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. + {{% /admonition %}} + +## Play Demo + +You can also take a look at the live Dashboards on play using this [link](https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github). diff --git a/docs/sources/examples/index.md b/docs/sources/examples/index.md deleted file mode 100644 index 8c7f86d9..00000000 --- a/docs/sources/examples/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: The GitHub data source lets you visualize GitHub API data in Grafana dashboards. -keywords: - - data source - - github - - github repository - - API -labels: - products: - - oss - - enterprise - - grafana cloud -menuTitle: GitHub data source -title: GitHub data source plugin for Grafana -weight: 10 ---- - -## Sample Dashboard - -For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) - -The sample dashboard can be obtained from either of two places. - -1. From the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) - -2. From the official [repository](https://github.com/grafana/github-datasource/) - -If loading it from the official repository, open Grafana and click "Import Dashboard". - -Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. diff --git a/docs/sources/faq/_index.md b/docs/sources/faq/_index.md new file mode 100644 index 00000000..acb9a479 --- /dev/null +++ b/docs/sources/faq/_index.md @@ -0,0 +1,41 @@ +--- +title: 'Frequently Asked Questions' +menuTitle: Frequently Asked Questions +description: Frequently Asked Questions +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 600 +--- + +# Frequently Asked Questions + +**Q. I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared access_token?** + +No. This requires changes in Grafana first. See this issue in the Grafana project. + +**Q. Why does it sometimes take up to 5 minutes for my new pull request / new issue / new commit to show up?** + +We have aggressive caching enabled due to GitHub's rate limiting policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily. + +**Q. Why are there two selection options for Pull Requests and Issue times when creating annotations?** + +There are two times that affect an annotation: + +* The time range of the dashboard or panel +* The time that should be used to display the event on the graph + +The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. + +The second selection is used to determine where on the graph the event should be displayed. + +Typically these will be the same, however there are some cases where you may want them to be different. diff --git a/docs/sources/report-issues/_index.md b/docs/sources/report-issues/_index.md new file mode 100644 index 00000000..3d138ae1 --- /dev/null +++ b/docs/sources/report-issues/_index.md @@ -0,0 +1,22 @@ +--- +title: 'Reporting Issues' +menuTitle: Reporting Issues +description: Reporting Issues +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 700 +--- + +# Reporting Issues + +Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs and feature requests. diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md new file mode 100644 index 00000000..4233c3fd --- /dev/null +++ b/docs/sources/setup/_index.md @@ -0,0 +1,25 @@ +--- +title: 'Install & Configure' +menuTitle: Setup +description: Install & Configure +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 100 +--- + +# Installation & Configuration + +- [Installation](./installation) +- [Configuration](./configuration) +- [Authentication](./authentication) +- [Provisioning](./provisioning) diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index e69de29b..ffd8d31e 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -0,0 +1,56 @@ +--- +slug: '/installation' +title: 'Installation' +menuTitle: Installation +description: This document introduces the GitHub data source +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 101 +--- + +# Installing Infinity data source plugin + +There are multiple ways to install this plugin into your grafana instance + +## Install from Plugin Catalog + +Install the plugin directly within the Grafana WebUI using the [plugin catalog](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-catalog). + +## Install from grafana.com + +Install the plugin from the [grafana.com plugins page](https://grafana.com/grafana/plugins/grafana-github-datasource/?tab=installation) using the instructions provided there. With this installation, you will get the latest published version of the plugin. + +## Install from GitHub + +Download the required version of the release zip file from [github](https://github.com/grafana/github-datasource/releases/) and extract it into your grafana plugin folder. Then restart Grafana. + +## Install using grafana-cli + +If you are using grafana-cli, execute the following command to install the latest published version of the plugin + +```bash +grafana-cli plugins install grafana-github-datasource +``` + +If you need custom version of the plugin from github, you can install using the following command. + +```bash +grafana-cli --pluginUrl plugins install grafana-github-datasource +``` + +Example: + +```bash +grafana-cli --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource +``` + From 78d8f94506e899a1bfd7c020c37c286a7f8a015b Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 3 Jul 2024 11:54:13 +0200 Subject: [PATCH 08/61] added the provisioning and authentication sections --- docs/sources/examples/_index.md | 6 ++--- docs/sources/setup/authentication.md | 39 ++++++++++++++++++++++++++++ docs/sources/setup/configuration.md | 39 ++++++++++++++++++++++++++++ docs/sources/setup/installation.md | 3 +-- docs/sources/setup/provisioning.md | 31 +++++++++++++++++++--- 5 files changed, 109 insertions(+), 9 deletions(-) create mode 100644 docs/sources/setup/authentication.md diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index fcc26997..6980302d 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -1,7 +1,7 @@ --- -title: 'Examples' -menuTitle: Examples -description: Examples +title: 'Examples Dashboards' +menuTitle: Examples Dashboards +description: Examples Dashboards aliases: - github keywords: diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md new file mode 100644 index 00000000..09b517f7 --- /dev/null +++ b/docs/sources/setup/authentication.md @@ -0,0 +1,39 @@ +--- +slug: '/authentication' +title: 'Authentication' +menuTitle: Authentication +description: Authenticating the GitHub data source plugin +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 103 +--- + +# Authentication + +1. After completing the Access Token Permissions, navigate into Grafana UI and click on the Menu option on the top left. + +1. Navigate to the Connections and then click on the Data Sources. + +1. Click on the GitHub Data source plugin which you have installed. + +1. Go to its settings tab and at the bottom, paste the GitHub token which you have created above. + +**image** + +1. Click “Save & Test” and you should see a confirmation message similar to this, that indicates that the Plugin is successfully configured. + +**image** + + {{% admonition type="note" %}} + Incase, if there are some errors then please check the Grafana logs for troubleshooting. + {{% /admonition %}} diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index 3f3ac62c..a7230228 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -1,5 +1,44 @@ +--- +slug: '/configuration' +title: 'Configuration' +menuTitle: Configuration +description: Configuration of the GitHub data source plugin +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 102 +--- + +# Configuration + +You will need a GitHub Access Token to use the plugin. Below is a table that indicates what requirements must be matched before the plugin can be used. + +Options: + +| Setting | Required | +| --------------------- | -------- | +| Access token | true | +| Default Organization | false | +| Default Repository | true | +| GitHub Enterprise URL | false | + +To create a new Access Token, navigate to [Personal Access Tokens](https://github.com/settings/tokens) and press Generate new token. + ## Access Token Permissions +You will need to define the access permissions for your token in order to allow it to access the data. + +Here is a list of the required minimum permissions defined below: + For all repositories: - `public_repo` diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index ffd8d31e..d7043374 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -2,7 +2,7 @@ slug: '/installation' title: 'Installation' menuTitle: Installation -description: This document introduces the GitHub data source +description: Installation of the GitHub data source plugin aliases: - github keywords: @@ -53,4 +53,3 @@ Example: ```bash grafana-cli --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource ``` - diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index ffc9a477..000165f2 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -1,8 +1,30 @@ -### Provisioning +--- +slug: '/provisioning' +title: 'Provisioning' +menuTitle: Provisioning +description: Provisioning the GitHub data source plugin +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 104 +--- -[It’s possible to configure data sources using config files with Grafana’s provisioning system](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). +# Provisioning -#### With the [prom-operator](https://github.com/prometheus-operator/prometheus-operator) +It’s possible to configure data sources using config files with [Grafana’s provisioning system](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). + +**Example** + +Here is an example to provision the Data source while using the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) ```yaml promop: @@ -14,4 +36,5 @@ promop: owner: '' repository: '' secureJsonData: - accessToken: '' \ No newline at end of file + accessToken: '' +``` From d270db5c3a1be6d71384521064b178ca21d8f216 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 3 Jul 2024 12:22:59 +0200 Subject: [PATCH 09/61] added variables and macros section --- docs/sources/variables-and-macros/_index.md | 38 ++++++++++--------- docs/sources/variables-and-macros/macros.md | 0 .../sources/variables-and-macros/variables.md | 0 3 files changed, 21 insertions(+), 17 deletions(-) create mode 100644 docs/sources/variables-and-macros/macros.md create mode 100644 docs/sources/variables-and-macros/variables.md diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index 1e5bbc96..ac2de583 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -1,19 +1,23 @@ -## Variables +--- +title: 'Variables & Macros' +menuTitle: Variables & Macros +description: Variables & Macros +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 200 +--- -[Variables](https://grafana.com/docs/grafana/latest/variables/) allow you to substitute values in a panel with pre-defined values. +# Variables & Macros -![Creating Variables](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/variables-create.png) - -You can reference them inside queries, allowing users to configure parameters such as `Query` or `Repository`. - -![Using Variables inside queries](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/using-variables.png) - -## Macros - -You can use the following macros in your queries - -| Macro Name | Syntax | Description | Example | -| ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | -| multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | -| | | When using **all** in multi variable, use **\*** as custom all value | | -| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | \ No newline at end of file +- [Variables](./variables) +- [Macros](./macros) \ No newline at end of file diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md new file mode 100644 index 00000000..e69de29b From 8a31c839a5b6a2c974b58d016e2aba2f9039bc58 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 3 Jul 2024 12:46:33 +0200 Subject: [PATCH 10/61] completed the variables and macros section --- docs/sources/variables-and-macros/macros.md | 31 ++++++++++++++++ .../sources/variables-and-macros/variables.md | 35 +++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index e69de29b..c3b04f31 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -0,0 +1,31 @@ +--- +slug: '/macros' +title: 'Macros' +menuTitle: Macros +description: Using Macros for the GitHub data source plugin +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 202 +--- + +# Macros + +A macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible and adaptable to changing conditions. + +You can use the following macros in your queries + +| Macro Name | Syntax | Description | Example | +| ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | +| multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | +| | | When using **all** in multi variable, use **\*** as custom all value | | +| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | \ No newline at end of file diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index e69de29b..10881fba 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -0,0 +1,35 @@ +--- +slug: '/variables' +title: 'Variables' +menuTitle: Variables +description: Using Variables for the GitHub data source plugin +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 201 +--- + +# Variables + +[Variable](https://grafana.com/docs/grafana/latest/variables/) is a placeholder for a value that can be used in queries for a dashboard. + +Variables allow you to create more interactive and dynamic dashboards by replacing hard-coded values with dynamic options. They are displayed as dropdown lists at the top of the dashboard, making it easy to change the data being displayed. + +**Example** + +Here is an example of creating a Dashboard variable: + +![Creating Variables](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/variables-create.png) + +You can reference them inside queries, allowing users to configure parameters such as `Query` or `Repository`. + +![Using Variables inside queries](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/using-variables.png) \ No newline at end of file From 2d4777bf4f72a1b897a51d58eff896092f8fec59 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 3 Jul 2024 22:32:30 +0200 Subject: [PATCH 11/61] fixed links images and text --- docs/sources/_index.md | 17 ++++++++++--- docs/sources/annotations/_index.md | 36 +++++++++++++++++++++++++--- docs/sources/examples/_index.md | 13 ++++++---- docs/sources/setup/authentication.md | 7 +++--- docs/sources/setup/configuration.md | 4 ++-- docs/sources/setup/provisioning.md | 2 +- 6 files changed, 61 insertions(+), 18 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index dc5a158b..cfd77ddd 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -58,6 +58,17 @@ Caching on this plugin is always enabled. The GitHub data source plugin has the following requirements: -- A GitHub account. -- Any free or paid Grafana Cloud plan or an activated on-prem Grafana Enterprise license. Contracted Cloud customers should refer to their agreement. -- Port 3000 enabled. +- A [GitHub](https://github.com/) or [GitHub Enterprise](https://github.com/enterprise) account. +- Any free or paid [Grafana Cloud](https://grafana.com/pricing/) plan or an [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) license. Contracted Cloud customers should refer to their agreement. +- Port `3000` enabled. + +## Get the most out of the plugin + +- Add [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations/) +- Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/) +- Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/) + +### Read More + +- [GitHub v4 client library](https://github.com/shurcooL/githubv4) +- [Manage personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 1d0b2107..1d815d92 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -1,8 +1,34 @@ -## Annotations +--- +title: 'Annotations' +menuTitle: Annotations +description: Using Annotations for the GitHub data source plugin +aliases: + - github +keywords: + - data source + - github + - github repository + - API +labels: + products: + - oss + - enterprise + - cloud +weight: 400 +--- + +# Annotations + +[Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations) let you extract data from a data source and use it to annotate a dashboard. + +To create annotations, you need to specify at least the following two fields: + +- A String field for the annotation text +- A Time field for the annotation time Annotations overlay events on a graph. -![Annotations on a graph](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/annotations.png) +![Annotations on a graph](/media/docs/grafana/data-sources/github/annotations.png) With annotations, you can display: @@ -16,4 +42,8 @@ on a graph. All annotations require that you select a field to display on the annotation, and a field that represents the time that the event occurred. -![Annotations editor](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/annotations-editor.png) \ No newline at end of file +![Annotations editor](/media/docs/grafana/data-sources/github/annotations-editor.png) + +If you want to add titles or tags to the annotations, you can add additional Fields with the appropriate types. + +For more information on how to configure a query, refer to [Built-in query editor](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/#built-in-query). diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 6980302d..702b6e1e 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -27,11 +27,14 @@ For documentation on importing dashboards, check out the documentation on [grafa The sample dashboard can be obtained from either of two places. -1. Importing from the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) -1. From the Grafana Web UI: - 1. Navigate to Connections and then click Data sources. - 1. Select the GitHub plugin and click the Dashboards tab. - 1. Click Import. +- Importing from the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) + +OR + +- From the Grafana Web UI: + 1. Navigate to Connections and then click Data sources. + 1. Select the GitHub plugin and click the Dashboards tab. + 1. Click Import. {{% admonition type="note" %}} If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index 09b517f7..b7028503 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -27,12 +27,11 @@ weight: 103 1. Click on the GitHub Data source plugin which you have installed. 1. Go to its settings tab and at the bottom, paste the GitHub token which you have created above. + ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) -**image** +1. Click “Save & Test” button and you should see a confirmation message similar to this, that indicates that the Plugin is successfully configured. -1. Click “Save & Test” and you should see a confirmation message similar to this, that indicates that the Plugin is successfully configured. - -**image** + ![Testing Data source](/media/docs/grafana/data-sources/github/github-plugin-config-success.png) {{% admonition type="note" %}} Incase, if there are some errors then please check the Grafana logs for troubleshooting. diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index a7230228..a4c6b557 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -20,7 +20,7 @@ weight: 102 # Configuration -You will need a GitHub Access Token to use the plugin. Below is a table that indicates what requirements must be matched before the plugin can be used. +You will need a GitHub Access Token to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. Options: @@ -55,4 +55,4 @@ For Github projects: An extra setting is required for private repositories -- `repo (Full control of private repositories)` \ No newline at end of file +- `repo (Full control of private repositories)` diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index 000165f2..e29e5eb5 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -20,7 +20,7 @@ weight: 104 # Provisioning -It’s possible to configure data sources using config files with [Grafana’s provisioning system](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). +You can define and configure the GitHub data source in YAML files as part of Grafana’s provisioning system. For more information about provisioning a data source, and for available configuration options, see [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). **Example** From dfca852818a639ace6739fcccea45bc96f867dfb Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 3 Jul 2024 22:37:43 +0200 Subject: [PATCH 12/61] run prettier --- docs/sources/_index.md | 2 +- docs/sources/examples/_index.md | 7 ++++--- docs/sources/faq/_index.md | 4 ++-- docs/sources/variables-and-macros/_index.md | 2 +- docs/sources/variables-and-macros/macros.md | 2 +- docs/sources/variables-and-macros/variables.md | 4 ++-- 6 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index cfd77ddd..e049cdee 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -1,5 +1,5 @@ --- -description: The GitHub data source lets you visualize GitHub API data in Grafana dashboards. +description: The GitHub data source lets you visualize GitHub data in Grafana dashboards. keywords: - data source - github diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 702b6e1e..8c2fa9e9 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -32,13 +32,14 @@ The sample dashboard can be obtained from either of two places. OR - From the Grafana Web UI: + 1. Navigate to Connections and then click Data sources. 1. Select the GitHub plugin and click the Dashboards tab. 1. Click Import. - {{% admonition type="note" %}} - If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. - {{% /admonition %}} + {{% admonition type="note" %}} + If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. + {{% /admonition %}} ## Play Demo diff --git a/docs/sources/faq/_index.md b/docs/sources/faq/_index.md index acb9a479..1a60001e 100644 --- a/docs/sources/faq/_index.md +++ b/docs/sources/faq/_index.md @@ -31,8 +31,8 @@ We have aggressive caching enabled due to GitHub's rate limiting policies. When There are two times that affect an annotation: -* The time range of the dashboard or panel -* The time that should be used to display the event on the graph +- The time range of the dashboard or panel +- The time that should be used to display the event on the graph The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index ac2de583..d9e10483 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -20,4 +20,4 @@ weight: 200 # Variables & Macros - [Variables](./variables) -- [Macros](./macros) \ No newline at end of file +- [Macros](./macros) diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index c3b04f31..c53f9d15 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -28,4 +28,4 @@ You can use the following macros in your queries | ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | | | | When using **all** in multi variable, use **\*** as custom all value | | -| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | \ No newline at end of file +| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index 10881fba..07463608 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -28,8 +28,8 @@ Variables allow you to create more interactive and dynamic dashboards by replaci Here is an example of creating a Dashboard variable: -![Creating Variables](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/variables-create.png) +![Creating Variables](/media/docs/grafana/data-sources/github/variables-create.png) You can reference them inside queries, allowing users to configure parameters such as `Query` or `Repository`. -![Using Variables inside queries](https://github.com/grafana/github-datasource/raw/main/docs/screenshots/using-variables.png) \ No newline at end of file +![Using Variables inside queries](/media/docs/grafana/data-sources/github/using-variables.png) \ No newline at end of file From 47b64228ef926a8566b57283313cb4c7bcffa37d Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 9 Jul 2024 11:31:35 +0200 Subject: [PATCH 13/61] Apply suggestions from code review reviews looks good. Thanks Co-authored-by: Ivana Huckova <30407135+ivanahuckova@users.noreply.github.com> --- docs/sources/_index.md | 46 ++++++++++--------- docs/sources/annotations/_index.md | 2 +- docs/sources/examples/_index.md | 22 ++++----- docs/sources/faq/_index.md | 8 ++-- docs/sources/report-issues/_index.md | 8 ++-- docs/sources/setup/_index.md | 4 +- docs/sources/setup/authentication.md | 10 ++-- docs/sources/setup/configuration.md | 4 +- docs/sources/setup/installation.md | 8 ++-- docs/sources/variables-and-macros/_index.md | 8 ++-- docs/sources/variables-and-macros/macros.md | 4 +- .../sources/variables-and-macros/variables.md | 8 ++-- 12 files changed, 68 insertions(+), 64 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index e049cdee..7dc9fc57 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -19,36 +19,40 @@ weight: 10 The GitHub datasource allows GitHub API data to be visually represented in Grafana dashboards. -{{< docs/play title="GitHub Data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} +{{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} ## GitHub API V4 (GraphQL) This datasource uses the [`githubv4` package](https://github.com/shurcooL/githubv4), which is under active development. -## Key Features +## Key features -The Grafana GitHub Data source plugin provides several features, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. +The Grafana GitHub data source plugin provides several features, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. -### Backend +### Query types -- [x] Releases -- [x] Commits -- [x] Repositories -- [x] Stargazers -- [x] Issues -- [x] Organizations -- [x] Labels -- [x] Milestones -- [x] Response Caching -- [x] Projects -- [x] Workflows -- [ ] Deploys +- Commits +- Issues +- Contributors +- Tags +- Releases +- Pull Requests +- Labels +- Repositories +- Milestones +- Packages +- Vulnerabilities +- Projects +- Stargazers +- Workflows +- Workflow Usage -### Frontend +### Supported features -- [x] Visualize queries -- [x] Template variables -- [x] Annotations +- Visualize queries +- Template variables +- Annotations +- Query caching ### Caching @@ -68,7 +72,7 @@ The GitHub data source plugin has the following requirements: - Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/) - Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/) -### Read More +### Read more - [GitHub v4 client library](https://github.com/shurcooL/githubv4) - [Manage personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 1d815d92..97738186 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -1,7 +1,7 @@ --- title: 'Annotations' menuTitle: Annotations -description: Using Annotations for the GitHub data source plugin +description: Using annotations for the GitHub data source plugin aliases: - github keywords: diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 8c2fa9e9..5763ccd4 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -1,7 +1,7 @@ --- -title: 'Examples Dashboards' -menuTitle: Examples Dashboards -description: Examples Dashboards +title: 'Examples dashboards' +menuTitle: Examples dashboards +description: Examples dashboards aliases: - github keywords: @@ -17,11 +17,11 @@ labels: weight: 500 --- -# Example Dashboard +# Example dashboard Here are some examples dashboards that you can use for your usecase. -## Pre-configure Dashboards +## Pre-configure dashboards For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard). @@ -31,16 +31,16 @@ The sample dashboard can be obtained from either of two places. OR -- From the Grafana Web UI: +- From the GitHub data source configuration page: - 1. Navigate to Connections and then click Data sources. - 1. Select the GitHub plugin and click the Dashboards tab. - 1. Click Import. + 1. Navigate to "Connections" and then click "Data sources". + 1. Select the GitHub plugin and click the "Dashboards" tab. + 1. Click "Import". {{% admonition type="note" %}} If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. {{% /admonition %}} -## Play Demo +## Play demo -You can also take a look at the live Dashboards on play using this [link](https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github). +You can also take a look at the live dashboards on play using this [link](https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github). diff --git a/docs/sources/faq/_index.md b/docs/sources/faq/_index.md index 1a60001e..acb048f8 100644 --- a/docs/sources/faq/_index.md +++ b/docs/sources/faq/_index.md @@ -1,7 +1,7 @@ --- -title: 'Frequently Asked Questions' -menuTitle: Frequently Asked Questions -description: Frequently Asked Questions +title: 'Frequently asked questions' +menuTitle: Frequently asked questions +description: Frequently asked questions aliases: - github keywords: @@ -17,7 +17,7 @@ labels: weight: 600 --- -# Frequently Asked Questions +# Frequently asked questions **Q. I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared access_token?** diff --git a/docs/sources/report-issues/_index.md b/docs/sources/report-issues/_index.md index 3d138ae1..60e589e5 100644 --- a/docs/sources/report-issues/_index.md +++ b/docs/sources/report-issues/_index.md @@ -1,7 +1,7 @@ --- -title: 'Reporting Issues' -menuTitle: Reporting Issues -description: Reporting Issues +title: 'Reporting issues' +menuTitle: Reporting issues +description: Reporting issues aliases: - github keywords: @@ -17,6 +17,6 @@ labels: weight: 700 --- -# Reporting Issues +# Reporting issues Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs and feature requests. diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md index 4233c3fd..dc8f8f3c 100644 --- a/docs/sources/setup/_index.md +++ b/docs/sources/setup/_index.md @@ -1,7 +1,7 @@ --- -title: 'Install & Configure' +title: 'Install & configure' menuTitle: Setup -description: Install & Configure +description: Install & configure aliases: - github keywords: diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index b7028503..3c557fb8 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -20,18 +20,18 @@ weight: 103 # Authentication -1. After completing the Access Token Permissions, navigate into Grafana UI and click on the Menu option on the top left. +1. After completing the **Access Token Permissions** in GitHub, navigate into Grafana and click on the menu option on the top left. -1. Navigate to the Connections and then click on the Data Sources. +1. Navigate to the "Connections" and then click on the "Data sources". -1. Click on the GitHub Data source plugin which you have installed. +1. Click on the GitHub data source plugin which you have installed. 1. Go to its settings tab and at the bottom, paste the GitHub token which you have created above. ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) -1. Click “Save & Test” button and you should see a confirmation message similar to this, that indicates that the Plugin is successfully configured. +1. Click "Save & Test" button and you should see a confirmation message similar to this, that indicates that the plugin is successfully configured. - ![Testing Data source](/media/docs/grafana/data-sources/github/github-plugin-config-success.png) + ![Testing data source](/media/docs/grafana/data-sources/github/github-plugin-config-success.png) {{% admonition type="note" %}} Incase, if there are some errors then please check the Grafana logs for troubleshooting. diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index a4c6b557..59d88ee1 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -20,7 +20,7 @@ weight: 102 # Configuration -You will need a GitHub Access Token to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. +You will need a **GitHub Access Token** to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. Options: @@ -33,7 +33,7 @@ Options: To create a new Access Token, navigate to [Personal Access Tokens](https://github.com/settings/tokens) and press Generate new token. -## Access Token Permissions +## Access token permissions You will need to define the access permissions for your token in order to allow it to access the data. diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index d7043374..9d333d71 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -18,13 +18,13 @@ labels: weight: 101 --- -# Installing Infinity data source plugin +# Installing GitHub data source plugin -There are multiple ways to install this plugin into your grafana instance +There are multiple ways to install this plugin into your Grafana instance -## Install from Plugin Catalog +## Install from plugin catalog -Install the plugin directly within the Grafana WebUI using the [plugin catalog](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-catalog). +Install the plugin directly within the Grafana web UI using the [plugin catalog](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-catalog). ## Install from grafana.com diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index d9e10483..13ba82bc 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -1,7 +1,7 @@ --- -title: 'Variables & Macros' -menuTitle: Variables & Macros -description: Variables & Macros +title: 'Variables & macros' +menuTitle: Variables & macros +description: Variables & macros aliases: - github keywords: @@ -17,7 +17,7 @@ labels: weight: 200 --- -# Variables & Macros +# Variables & macros - [Variables](./variables) - [Macros](./macros) diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index c53f9d15..6254fba0 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -2,7 +2,7 @@ slug: '/macros' title: 'Macros' menuTitle: Macros -description: Using Macros for the GitHub data source plugin +description: Using macros for the GitHub data source plugin aliases: - github keywords: @@ -24,7 +24,7 @@ A macro is a feature that allows you to simplify the syntax and add dynamic part You can use the following macros in your queries -| Macro Name | Syntax | Description | Example | +| Macro name | Syntax | Description | Example | | ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | | | | When using **all** in multi variable, use **\*** as custom all value | | diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index 07463608..39f86a83 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -2,7 +2,7 @@ slug: '/variables' title: 'Variables' menuTitle: Variables -description: Using Variables for the GitHub data source plugin +description: Using variables for the GitHub data source plugin aliases: - github keywords: @@ -26,10 +26,10 @@ Variables allow you to create more interactive and dynamic dashboards by replaci **Example** -Here is an example of creating a Dashboard variable: +Here is an example of creating a dashboard variable: -![Creating Variables](/media/docs/grafana/data-sources/github/variables-create.png) +![Creating variables](/media/docs/grafana/data-sources/github/variables-create.png) You can reference them inside queries, allowing users to configure parameters such as `Query` or `Repository`. -![Using Variables inside queries](/media/docs/grafana/data-sources/github/using-variables.png) \ No newline at end of file +![Using variables inside queries](/media/docs/grafana/data-sources/github/using-variables.png) \ No newline at end of file From 223a905e67be079a53e25bc343c0c334e2c43f1c Mon Sep 17 00:00:00 2001 From: Ivana Huckova Date: Tue, 9 Jul 2024 13:11:28 +0200 Subject: [PATCH 14/61] Fix spell --- docs/sources/examples/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 5763ccd4..da720d97 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -19,7 +19,7 @@ weight: 500 # Example dashboard -Here are some examples dashboards that you can use for your usecase. +Here are some examples dashboards that you can use for your use case. ## Pre-configure dashboards From 47c9c6f071922dd71e6de9bc9fd12b29e7e52bbf Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 9 Jul 2024 23:15:51 +0200 Subject: [PATCH 15/61] Apply suggestions from code review Thanks for the review. Approving these changes Co-authored-by: Jack Baldry --- docs/sources/_index.md | 6 +++--- docs/sources/annotations/_index.md | 7 +++---- docs/sources/setup/_index.md | 5 +---- docs/sources/setup/authentication.md | 9 ++++----- docs/sources/setup/configuration.md | 2 +- docs/sources/setup/installation.md | 1 - docs/sources/setup/provisioning.md | 4 ++-- 7 files changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 7dc9fc57..38234d3d 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -17,7 +17,7 @@ weight: 10 # Overview -The GitHub datasource allows GitHub API data to be visually represented in Grafana dashboards. +With the GitHub data source, you can visualize GitHub API data in Grafana dashboards. {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} @@ -36,7 +36,7 @@ The Grafana GitHub data source plugin provides several features, allow you to tr - Contributors - Tags - Releases -- Pull Requests +- Pull requests - Labels - Repositories - Milestones @@ -45,7 +45,7 @@ The Grafana GitHub data source plugin provides several features, allow you to tr - Projects - Stargazers - Workflows -- Workflow Usage +- Workflow usage ### Supported features diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 97738186..6df9d1e3 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -30,20 +30,19 @@ Annotations overlay events on a graph. ![Annotations on a graph](/media/docs/grafana/data-sources/github/annotations.png) -With annotations, you can display: +With annotations, you can display the following GitHub resources on a graph: - Commits - Issues -- Pull Requests +- Pull requests - Releases - Tags -on a graph. All annotations require that you select a field to display on the annotation, and a field that represents the time that the event occurred. ![Annotations editor](/media/docs/grafana/data-sources/github/annotations-editor.png) -If you want to add titles or tags to the annotations, you can add additional Fields with the appropriate types. +If you want to add titles or tags to the annotations, you can add additional fields with the appropriate types. For more information on how to configure a query, refer to [Built-in query editor](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/#built-in-query). diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md index dc8f8f3c..2e5fc5cf 100644 --- a/docs/sources/setup/_index.md +++ b/docs/sources/setup/_index.md @@ -19,7 +19,4 @@ weight: 100 # Installation & Configuration -- [Installation](./installation) -- [Configuration](./configuration) -- [Authentication](./authentication) -- [Provisioning](./provisioning) +{{< section menuTitle="true" withDescriptions="true" >}} diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index 3c557fb8..7076c4b9 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -1,5 +1,4 @@ --- -slug: '/authentication' title: 'Authentication' menuTitle: Authentication description: Authenticating the GitHub data source plugin @@ -22,7 +21,7 @@ weight: 103 1. After completing the **Access Token Permissions** in GitHub, navigate into Grafana and click on the menu option on the top left. -1. Navigate to the "Connections" and then click on the "Data sources". +1. Browse to the **Connections** menu and then click on the **Data sources**. 1. Click on the GitHub data source plugin which you have installed. @@ -33,6 +32,6 @@ weight: 103 ![Testing data source](/media/docs/grafana/data-sources/github/github-plugin-config-success.png) - {{% admonition type="note" %}} - Incase, if there are some errors then please check the Grafana logs for troubleshooting. - {{% /admonition %}} + {{< admonition type="note" >}} + If you see errors, check the Grafana logs for troubleshooting. + {{< /admonition >}} diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index 59d88ee1..3e970aa3 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -48,7 +48,7 @@ For all repositories: - `read:user` - `user:email` -For Github projects: +For GitHub projects: - `read:org` - `read:project` diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 9d333d71..7c8a460d 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -1,5 +1,4 @@ --- -slug: '/installation' title: 'Installation' menuTitle: Installation description: Installation of the GitHub data source plugin diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index e29e5eb5..0a7da2f2 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -1,5 +1,4 @@ --- -slug: '/provisioning' title: 'Provisioning' menuTitle: Provisioning description: Provisioning the GitHub data source plugin @@ -20,7 +19,8 @@ weight: 104 # Provisioning -You can define and configure the GitHub data source in YAML files as part of Grafana’s provisioning system. For more information about provisioning a data source, and for available configuration options, see [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). +You can define and configure the GitHub data source in YAML files with Grafana provisioning. +For more information about provisioning a data source, and for available configuration options, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). **Example** From 3a7a0e41409ba0e08679e07aa901e695355fe74f Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Thu, 11 Jul 2024 14:35:07 +0200 Subject: [PATCH 16/61] remove unnecssary information --- docs/sources/_index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 38234d3d..f4f47b2d 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -21,10 +21,6 @@ With the GitHub data source, you can visualize GitHub API data in Grafana dashbo {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} -## GitHub API V4 (GraphQL) - -This datasource uses the [`githubv4` package](https://github.com/shurcooL/githubv4), which is under active development. - ## Key features The Grafana GitHub data source plugin provides several features, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. From 65b134fcf3ee88a439812309459dc801fb90d15f Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Thu, 11 Jul 2024 14:42:50 +0200 Subject: [PATCH 17/61] Apply suggestions from code review suggestion looks good Co-authored-by: Jack Baldry --- docs/sources/_index.md | 2 +- docs/sources/setup/_index.md | 6 +++--- docs/sources/setup/authentication.md | 12 +++++------- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index f4f47b2d..dd8e3e08 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -15,7 +15,7 @@ title: GitHub data source plugin for Grafana weight: 10 --- -# Overview +# GitHub data source plugin for Grafana With the GitHub data source, you can visualize GitHub API data in Grafana dashboards. diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md index 2e5fc5cf..0f8b0d99 100644 --- a/docs/sources/setup/_index.md +++ b/docs/sources/setup/_index.md @@ -1,7 +1,7 @@ --- -title: 'Install & configure' +title: Set up the GitHub data source plugin menuTitle: Setup -description: Install & configure +description: Learn how to install and configure the GitHub data source plugin. aliases: - github keywords: @@ -17,6 +17,6 @@ labels: weight: 100 --- -# Installation & Configuration +# Set up the GitHub data source plugin {{< section menuTitle="true" withDescriptions="true" >}} diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index 7076c4b9..3440981b 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -1,7 +1,7 @@ --- -title: 'Authentication' -menuTitle: Authentication -description: Authenticating the GitHub data source plugin +title: 'Configure authentication' +menuTitle: Configure authentication +description: Configure the GitHub data source plugin to authenticate to GitHub. aliases: - github keywords: @@ -17,7 +17,7 @@ labels: weight: 103 --- -# Authentication +# Configure authentication 1. After completing the **Access Token Permissions** in GitHub, navigate into Grafana and click on the menu option on the top left. @@ -28,9 +28,7 @@ weight: 103 1. Go to its settings tab and at the bottom, paste the GitHub token which you have created above. ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) -1. Click "Save & Test" button and you should see a confirmation message similar to this, that indicates that the plugin is successfully configured. - - ![Testing data source](/media/docs/grafana/data-sources/github/github-plugin-config-success.png) +1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". {{< admonition type="note" >}} If you see errors, check the Grafana logs for troubleshooting. From 5624cd37a4fae0adceb662d35b03ffee64304445 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Thu, 11 Jul 2024 17:17:21 +0200 Subject: [PATCH 18/61] fixed intro --- docs/sources/_index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index dd8e3e08..146245e0 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -17,14 +17,12 @@ weight: 10 # GitHub data source plugin for Grafana -With the GitHub data source, you can visualize GitHub API data in Grafana dashboards. +The Grafana GitHub data source plugin provides, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} ## Key features -The Grafana GitHub data source plugin provides several features, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. - ### Query types - Commits From c3fc9bd0d7d9d9092726bb1198b61364c0e05091 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Thu, 11 Jul 2024 20:03:05 +0200 Subject: [PATCH 19/61] fixed requrement section --- docs/sources/_index.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 146245e0..3ebca564 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -21,9 +21,9 @@ The Grafana GitHub data source plugin provides, allow you to track and analyze G {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} -## Key features +The plugin provide the features listed below: -### Query types +## Query types - Commits - Issues @@ -41,14 +41,14 @@ The Grafana GitHub data source plugin provides, allow you to track and analyze G - Workflows - Workflow usage -### Supported features +## Supported features - Visualize queries - Template variables - Annotations - Query caching -### Caching +## Caching Caching on this plugin is always enabled. @@ -56,9 +56,12 @@ Caching on this plugin is always enabled. The GitHub data source plugin has the following requirements: -- A [GitHub](https://github.com/) or [GitHub Enterprise](https://github.com/enterprise) account. -- Any free or paid [Grafana Cloud](https://grafana.com/pricing/) plan or an [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) license. Contracted Cloud customers should refer to their agreement. -- Port `3000` enabled. +- A free [GitHub](https://github.com/) or a [GitHub Enterprise](https://github.com/enterprise) account. +- Any of the following Grafana flavours: + - Grafana OSS + - Free or paid [Grafana Cloud](https://grafana.com/pricing/) server + - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server. + - Port `3000` enabled. ## Get the most out of the plugin From e897fb8494f6c82fb18edfc6cae78036f952bfd2 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Thu, 11 Jul 2024 20:05:10 +0200 Subject: [PATCH 20/61] fixed read more to further reading --- docs/sources/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 3ebca564..96d50a57 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -69,7 +69,7 @@ The GitHub data source plugin has the following requirements: - Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/) - Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/) -### Read more +### Further reading - [GitHub v4 client library](https://github.com/shurcooL/githubv4) - [Manage personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) From fbe652f421bbff57d3ff36295dd40d4aabf77e8e Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 10:38:40 +0200 Subject: [PATCH 21/61] removed aliases tag from metadata --- docs/sources/annotations/_index.md | 2 -- docs/sources/examples/_index.md | 2 -- docs/sources/faq/_index.md | 2 -- docs/sources/report-issues/_index.md | 2 -- docs/sources/setup/_index.md | 2 -- docs/sources/setup/authentication.md | 2 -- docs/sources/setup/configuration.md | 2 -- docs/sources/setup/installation.md | 2 -- docs/sources/setup/provisioning.md | 2 -- docs/sources/variables-and-macros/_index.md | 2 -- docs/sources/variables-and-macros/macros.md | 2 -- docs/sources/variables-and-macros/variables.md | 2 -- 12 files changed, 24 deletions(-) diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 6df9d1e3..fd425d4e 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -2,8 +2,6 @@ title: 'Annotations' menuTitle: Annotations description: Using annotations for the GitHub data source plugin -aliases: - - github keywords: - data source - github diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index da720d97..b0f9f6d0 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -2,8 +2,6 @@ title: 'Examples dashboards' menuTitle: Examples dashboards description: Examples dashboards -aliases: - - github keywords: - data source - github diff --git a/docs/sources/faq/_index.md b/docs/sources/faq/_index.md index acb048f8..1649c0c3 100644 --- a/docs/sources/faq/_index.md +++ b/docs/sources/faq/_index.md @@ -2,8 +2,6 @@ title: 'Frequently asked questions' menuTitle: Frequently asked questions description: Frequently asked questions -aliases: - - github keywords: - data source - github diff --git a/docs/sources/report-issues/_index.md b/docs/sources/report-issues/_index.md index 60e589e5..8a7d16e4 100644 --- a/docs/sources/report-issues/_index.md +++ b/docs/sources/report-issues/_index.md @@ -2,8 +2,6 @@ title: 'Reporting issues' menuTitle: Reporting issues description: Reporting issues -aliases: - - github keywords: - data source - github diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md index 0f8b0d99..f45075a4 100644 --- a/docs/sources/setup/_index.md +++ b/docs/sources/setup/_index.md @@ -2,8 +2,6 @@ title: Set up the GitHub data source plugin menuTitle: Setup description: Learn how to install and configure the GitHub data source plugin. -aliases: - - github keywords: - data source - github diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index 3440981b..a0931803 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -2,8 +2,6 @@ title: 'Configure authentication' menuTitle: Configure authentication description: Configure the GitHub data source plugin to authenticate to GitHub. -aliases: - - github keywords: - data source - github diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index 3e970aa3..924cb405 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -3,8 +3,6 @@ slug: '/configuration' title: 'Configuration' menuTitle: Configuration description: Configuration of the GitHub data source plugin -aliases: - - github keywords: - data source - github diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 7c8a460d..86c55b88 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -2,8 +2,6 @@ title: 'Installation' menuTitle: Installation description: Installation of the GitHub data source plugin -aliases: - - github keywords: - data source - github diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index 0a7da2f2..78ea576c 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -2,8 +2,6 @@ title: 'Provisioning' menuTitle: Provisioning description: Provisioning the GitHub data source plugin -aliases: - - github keywords: - data source - github diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index 13ba82bc..10d1d413 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -2,8 +2,6 @@ title: 'Variables & macros' menuTitle: Variables & macros description: Variables & macros -aliases: - - github keywords: - data source - github diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index 6254fba0..8fc1c87d 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -3,8 +3,6 @@ slug: '/macros' title: 'Macros' menuTitle: Macros description: Using macros for the GitHub data source plugin -aliases: - - github keywords: - data source - github diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index 39f86a83..f0c9795b 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -3,8 +3,6 @@ slug: '/variables' title: 'Variables' menuTitle: Variables description: Using variables for the GitHub data source plugin -aliases: - - github keywords: - data source - github From 7c12739448a1b2bf962e0c789abb598b1bb23b96 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 10:42:50 +0200 Subject: [PATCH 22/61] removed port information from requiremnts --- docs/sources/_index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 96d50a57..994a1041 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -61,7 +61,6 @@ The GitHub data source plugin has the following requirements: - Grafana OSS - Free or paid [Grafana Cloud](https://grafana.com/pricing/) server - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server. - - Port `3000` enabled. ## Get the most out of the plugin From 466bfe9f41eab47eb5634f8650626d09ea41066b Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 10:45:32 +0200 Subject: [PATCH 23/61] added report issues into homepage section --- docs/sources/_index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 994a1041..47622a07 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -68,6 +68,10 @@ The GitHub data source plugin has the following requirements: - Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/) - Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/) +## Reporting issues + +Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs and feature requests. + ### Further reading - [GitHub v4 client library](https://github.com/shurcooL/githubv4) From 87001d6c08657490ea7c16cda84e5becf38f5f2a Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 14:35:36 +0200 Subject: [PATCH 24/61] removed report-issues spearate page --- docs/sources/report-issues/_index.md | 20 -------------------- 1 file changed, 20 deletions(-) delete mode 100644 docs/sources/report-issues/_index.md diff --git a/docs/sources/report-issues/_index.md b/docs/sources/report-issues/_index.md deleted file mode 100644 index 8a7d16e4..00000000 --- a/docs/sources/report-issues/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: 'Reporting issues' -menuTitle: Reporting issues -description: Reporting issues -keywords: - - data source - - github - - github repository - - API -labels: - products: - - oss - - enterprise - - cloud -weight: 700 ---- - -# Reporting issues - -Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs and feature requests. From bfc0759c5b32d61f2a0e8eabc3b90ffa91af9ac6 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 14:36:32 +0200 Subject: [PATCH 25/61] removed faq page --- docs/sources/faq/_index.md | 39 -------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 docs/sources/faq/_index.md diff --git a/docs/sources/faq/_index.md b/docs/sources/faq/_index.md deleted file mode 100644 index 1649c0c3..00000000 --- a/docs/sources/faq/_index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 'Frequently asked questions' -menuTitle: Frequently asked questions -description: Frequently asked questions -keywords: - - data source - - github - - github repository - - API -labels: - products: - - oss - - enterprise - - cloud -weight: 600 ---- - -# Frequently asked questions - -**Q. I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared access_token?** - -No. This requires changes in Grafana first. See this issue in the Grafana project. - -**Q. Why does it sometimes take up to 5 minutes for my new pull request / new issue / new commit to show up?** - -We have aggressive caching enabled due to GitHub's rate limiting policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily. - -**Q. Why are there two selection options for Pull Requests and Issue times when creating annotations?** - -There are two times that affect an annotation: - -- The time range of the dashboard or panel -- The time that should be used to display the event on the graph - -The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. - -The second selection is used to determine where on the graph the event should be displayed. - -Typically these will be the same, however there are some cases where you may want them to be different. From 6a2881f1d909ea30a23d70662a79f5edc6298b03 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 20:00:50 +0200 Subject: [PATCH 26/61] improved the configuration section --- docs/sources/examples/_index.md | 22 ++++++++++++++++------ docs/sources/setup/configuration.md | 18 ++++++++++-------- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index b0f9f6d0..cd9a241c 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -17,9 +17,19 @@ weight: 500 # Example dashboard -Here are some examples dashboards that you can use for your use case. +There are multiple ways to use some of the examples dashboards that you can use for your use case. -## Pre-configure dashboards +1. Using pre-configured dashboards +1. Using play demo + +## 1. Using pre-configure dashboards + +There are two ways to use the pre-configure dashboards: + +- Importing from the official Website +- Importing from the Grafana server WebUI + +### Importing from the official Website For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard). @@ -27,18 +37,18 @@ The sample dashboard can be obtained from either of two places. - Importing from the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) -OR +### Importing from the Grafana server WebUI - From the GitHub data source configuration page: 1. Navigate to "Connections" and then click "Data sources". - 1. Select the GitHub plugin and click the "Dashboards" tab. - 1. Click "Import". + 2. Select the GitHub plugin and click the "Dashboards" tab. + 3. Click "Import". {{% admonition type="note" %}} If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. {{% /admonition %}} -## Play demo +## 2. Play demo You can also take a look at the live dashboards on play using this [link](https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github). diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index 924cb405..68169760 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -18,18 +18,20 @@ weight: 102 # Configuration -You will need a **GitHub Access Token** to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. +You will need a **personal access token** to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. Options: -| Setting | Required | -| --------------------- | -------- | -| Access token | true | -| Default Organization | false | -| Default Repository | true | -| GitHub Enterprise URL | false | +| Setting | Required | Details | +| --------------------- | -------- |-------------------------------------------------------| +| Access token | true | This is required to allow plugin to connect to GitHub | +| Default Organization | false | Only if you want to set a specfic organization as a default selection while creating Dashboards | +| Default Repository | true | A repository is required to access the data | +| GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | -To create a new Access Token, navigate to [Personal Access Tokens](https://github.com/settings/tokens) and press Generate new token. +Read more about [creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). + +To create a new personal access token, navigate to [Personal access tokens](https://github.com/settings/tokens) and press Generate new token. ## Access token permissions From ab620728cbbeb2018605bc47d49a2f202e41e060 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 15 Jul 2024 20:06:18 +0200 Subject: [PATCH 27/61] fixed typo --- docs/sources/setup/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index 68169760..e357091d 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -22,7 +22,7 @@ You will need a **personal access token** to use the plugin. Below is a table th Options: -| Setting | Required | Details | +| Setting | Required | Description | | --------------------- | -------- |-------------------------------------------------------| | Access token | true | This is required to allow plugin to connect to GitHub | | Default Organization | false | Only if you want to set a specfic organization as a default selection while creating Dashboards | From 76b763da024df6f6d098fbec8d0b97af45e9315a Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 06:24:12 +0200 Subject: [PATCH 28/61] fixed installation section --- docs/sources/setup/installation.md | 70 ++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 9 deletions(-) diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 86c55b88..4752730c 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -21,7 +21,14 @@ There are multiple ways to install this plugin into your Grafana instance ## Install from plugin catalog -Install the plugin directly within the Grafana web UI using the [plugin catalog](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-catalog). +1. Login to Grafana Web UI as *Server Admin* +1. Click **Administration** > **Plugins and data** > **Plugins** in the side navigation menu to view all plugins. +1. Type **GitHub** in the Search box +1. Click the **All** in the **State** filter option. +1. Click the plugin’s logo. +1. Click Install. + +Find more information about the [plugin catalog](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-catalog). ## Install from grafana.com @@ -29,17 +36,52 @@ Install the plugin from the [grafana.com plugins page](https://grafana.com/grafa ## Install from GitHub -Download the required version of the release zip file from [github](https://github.com/grafana/github-datasource/releases/) and extract it into your grafana plugin folder. Then restart Grafana. +1. Go to [Releases](https://github.com/grafana/github-datasource/releases/) on the GitHub project page. + +1. Find the release you want to install + +1. Download the release by clicking the release asset called `grafana-github-datasource-.zip`. You may need to un-collapse the **Assets** section to see it. + +1. Unarchive the plugin into the Grafana plugins directory: + + In Linux/macOS, you can use the following command to extract the plugin: + + ```bash + unzip grafana-github-datasource-.zip + mv grafana-github-datasource /var/lib/grafana/plugins + ``` + + In Windows, you can use the following command to extract the plugin: + + ```shell + Expand-Archive -Path grafana-github-datasource-.zip -DestinationPath C:\grafana\data\plugins + ``` + +1. Then restart Grafana. ## Install using grafana-cli If you are using grafana-cli, execute the following command to install the latest published version of the plugin -```bash -grafana-cli plugins install grafana-github-datasource -``` +1. Login to your machine as root user. + +1. In Linux/macOS, ypen your terminal and write the command: -If you need custom version of the plugin from github, you can install using the following command. + ```bash + grafana-cli plugins install grafana-github-datasource + ``` + + Similarly, if you are using Windows machine, use the following command: + + ```shell + grafana-cli.exe plugins install grafana-github-datasource + ``` + +1. Then restart Grafana. + +### Install custom version + +If you need custom version of the plugin from github, you can install using the following command: ```bash grafana-cli --pluginUrl plugins install grafana-github-datasource @@ -47,6 +89,16 @@ grafana-cli --pluginUrl plugins install grafana-github-datasource Example: -```bash -grafana-cli --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource -``` +1. In Linux/macOS: + + ```bash + grafana-cli --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource + ``` + +1. In Windows: + + ```shell + grafana-cli.exe --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource + ``` + +1. Then restart Grafana. From ae27952f9d1a0194f8e1347ac889511b9b9b9ff3 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 06:59:42 +0200 Subject: [PATCH 29/61] fixed minor changes --- docs/sources/setup/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 4752730c..33820aa7 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -1,7 +1,7 @@ --- title: 'Installation' menuTitle: Installation -description: Installation of the GitHub data source plugin +description: Install the GitHub data source plugin keywords: - data source - github @@ -15,7 +15,7 @@ labels: weight: 101 --- -# Installing GitHub data source plugin +# Install the GitHub data source plugin There are multiple ways to install this plugin into your Grafana instance From e4ce43e0030373b2b64dc3a0e453054a43b3e833 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 07:08:02 +0200 Subject: [PATCH 30/61] fixed macros --- docs/sources/variables-and-macros/macros.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index 8fc1c87d..322633f8 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -18,12 +18,12 @@ weight: 202 # Macros -A macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible and adaptable to changing conditions. +A macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible and adaptable to changing conditions. It's important to note that while not all data source plugins have macros as it availability and implementation depends on the specific design and capabilities of each plugin. -You can use the following macros in your queries +The GitHub data source plugin do support the macro feature and you can use the following macros in your queries: | Macro name | Syntax | Description | Example | | ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | | | | When using **all** in multi variable, use **\*** as custom all value | | -| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | +| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | \ No newline at end of file From e3a95a3139ecb7e9f8ce9c75cb6eefd4b2bf51e2 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 11:41:13 +0200 Subject: [PATCH 31/61] added note in configuration --- docs/sources/setup/authentication.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index a0931803..b35c9c49 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -31,3 +31,7 @@ weight: 103 {{< admonition type="note" >}} If you see errors, check the Grafana logs for troubleshooting. {{< /admonition >}} + + {{< admonition type="note" >}} + If you are using GitHub OAuth on Grafana, then it is not possible that the users to make requests with their individual GitHub accounts instead of a shared `access_token`. Please refer to [this issue](https://github.com/grafana/grafana/issues/26023) in the Grafana project. + {{< /admonition >}} From 913e484dbbc57fc9ba82e8c6d910cc90bf81cb27 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 11:45:49 +0200 Subject: [PATCH 32/61] added cache note --- docs/sources/_index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 47622a07..bbf323ab 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -52,6 +52,10 @@ The plugin provide the features listed below: Caching on this plugin is always enabled. +{{< admonition type="note" >}} +Sometimes it may take up to 5 minutes as we have aggressive caching enabled due to [GitHub's rate limiting](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28) policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily. +{{< /admonition >}} + ## Requirements The GitHub data source plugin has the following requirements: From 0982edd0632dcf23576c5a56d4a6087f9c35afd5 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 11:46:57 +0200 Subject: [PATCH 33/61] added annotation note --- docs/sources/annotations/_index.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index fd425d4e..9c5dafb9 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -36,7 +36,6 @@ With annotations, you can display the following GitHub resources on a graph: - Releases - Tags - All annotations require that you select a field to display on the annotation, and a field that represents the time that the event occurred. ![Annotations editor](/media/docs/grafana/data-sources/github/annotations-editor.png) @@ -44,3 +43,15 @@ All annotations require that you select a field to display on the annotation, an If you want to add titles or tags to the annotations, you can add additional fields with the appropriate types. For more information on how to configure a query, refer to [Built-in query editor](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/#built-in-query). + +{{< admonition type="note" >}} +There are two times that affect an annotation: + +The time range of the dashboard or panel +The time that should be used to display the event on the graph +The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. + +The second selection is used to determine where on the graph the event should be displayed. + +Typically these will be the same, however there are some cases where you may want them to be different. +{{< /admonition >}} From f7b66eae02f98e9e448ecc779926b804b3460719 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 11:59:40 +0200 Subject: [PATCH 34/61] fixed minor --- docs/sources/_index.md | 2 +- docs/sources/annotations/_index.md | 12 ++++++++---- docs/sources/examples/_index.md | 4 +++- docs/sources/setup/authentication.md | 2 +- docs/sources/setup/installation.md | 2 +- 5 files changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index bbf323ab..d5ecea4f 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -64,7 +64,7 @@ The GitHub data source plugin has the following requirements: - Any of the following Grafana flavours: - Grafana OSS - Free or paid [Grafana Cloud](https://grafana.com/pricing/) server - - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server. + - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server ## Get the most out of the plugin diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 9c5dafb9..86b21a85 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -45,11 +45,15 @@ If you want to add titles or tags to the annotations, you can add additional fie For more information on how to configure a query, refer to [Built-in query editor](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/#built-in-query). {{< admonition type="note" >}} -There are two times that affect an annotation: -The time range of the dashboard or panel -The time that should be used to display the event on the graph -The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. +There two selection options for Pull Requests and Issue times when creating annotation. This is because as there are two times that affect an annotation: + +- The time range of the dashboard or panel +- The time that should be used to display the event on the graph + +The first selection is used to filter the events that display on the graph. + +For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph. The second selection is used to determine where on the graph the event should be displayed. diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index cd9a241c..7b517bc0 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -51,4 +51,6 @@ The sample dashboard can be obtained from either of two places. ## 2. Play demo -You can also take a look at the live dashboards on play using this [link](https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github). +You can also take a look at the live dashboards on Grafana Play. + +{{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github" >}} diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index b35c9c49..d01c41b9 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -28,7 +28,7 @@ weight: 103 1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". - {{< admonition type="note" >}} + {{< admonition type="tip" >}} If you see errors, check the Grafana logs for troubleshooting. {{< /admonition >}} diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 33820aa7..03654e88 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -87,7 +87,7 @@ If you need custom version of the plugin from github, you can install using the grafana-cli --pluginUrl plugins install grafana-github-datasource ``` -Example: +**Example:** 1. In Linux/macOS: From bf9595d25160df7451c03924e66f940890477133 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 13:34:48 +0200 Subject: [PATCH 35/61] fixed provisioning annotation pages --- docs/sources/annotations/_index.md | 5 ++--- docs/sources/setup/authentication.md | 2 +- docs/sources/setup/configuration.md | 2 +- docs/sources/setup/provisioning.md | 15 ++++++++++----- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index 86b21a85..d9bfaf3a 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -44,9 +44,9 @@ If you want to add titles or tags to the annotations, you can add additional fie For more information on how to configure a query, refer to [Built-in query editor](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/#built-in-query). -{{< admonition type="note" >}} +## Pull Requests and Issue times when creating annotations -There two selection options for Pull Requests and Issue times when creating annotation. This is because as there are two times that affect an annotation: +While using annotations for pull request and issues, there two selection options. This is because as there are two times that affect an annotation: - The time range of the dashboard or panel - The time that should be used to display the event on the graph @@ -58,4 +58,3 @@ For example, if you select "closed at", only events that were "closed" in your d The second selection is used to determine where on the graph the event should be displayed. Typically these will be the same, however there are some cases where you may want them to be different. -{{< /admonition >}} diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index d01c41b9..047a18cc 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -1,5 +1,5 @@ --- -title: 'Configure authentication' +title: 'Creating access token' menuTitle: Configure authentication description: Configure the GitHub data source plugin to authenticate to GitHub. keywords: diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index e357091d..42417e66 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -26,7 +26,7 @@ Options: | --------------------- | -------- |-------------------------------------------------------| | Access token | true | This is required to allow plugin to connect to GitHub | | Default Organization | false | Only if you want to set a specfic organization as a default selection while creating Dashboards | -| Default Repository | true | A repository is required to access the data | +| Repository Access | true | Atleast a single repository is required to access the data | | GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | Read more about [creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index 78ea576c..c4f80c2e 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -17,8 +17,7 @@ weight: 104 # Provisioning -You can define and configure the GitHub data source in YAML files with Grafana provisioning. -For more information about provisioning a data source, and for available configuration options, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). +You can define and configure the GitHub data source in YAML files with Grafana provisioning. For more information about provisioning a data source, and for available configuration options, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). **Example** @@ -31,8 +30,14 @@ promop: - name: GitHub Repo Insights type: grafana-github-datasource jsonData: - owner: '' - repository: '' + owner: ’’ + repository: ’’ secureJsonData: - accessToken: '' + accessToken: ’’ ``` + +Replace; + +- _``_: name of the owner who owns the repository +- _``_: name of the repository to get the data +- _``_: your GitHub personal access token From e89fafa1e54d5654ace1081cc52f9e605846b3de Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 14:02:34 +0200 Subject: [PATCH 36/61] improved the configuration section --- docs/sources/setup/authentication.md | 12 ++++++++---- docs/sources/setup/configuration.md | 19 +++++++++++++++---- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/authentication.md index 047a18cc..7edce117 100644 --- a/docs/sources/setup/authentication.md +++ b/docs/sources/setup/authentication.md @@ -1,6 +1,6 @@ --- -title: 'Creating access token' -menuTitle: Configure authentication +title: 'Configuring data source' +menuTitle: Configure data source description: Configure the GitHub data source plugin to authenticate to GitHub. keywords: - data source @@ -15,9 +15,9 @@ labels: weight: 103 --- -# Configure authentication +# Configure Data source -1. After completing the **Access Token Permissions** in GitHub, navigate into Grafana and click on the menu option on the top left. +1. After creating the **personal access token** in GitHub, navigate into Grafana and click on the menu option on the top left. 1. Browse to the **Connections** menu and then click on the **Data sources**. @@ -28,6 +28,10 @@ weight: 103 1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". +## For GitHub Enterprise + +If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section (as show in the image of the **step 4** describe above) and paste the URL of your GitHub Enterprise. + {{< admonition type="tip" >}} If you see errors, check the Grafana logs for troubleshooting. {{< /admonition >}} diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/configuration.md index 42417e66..0847d306 100644 --- a/docs/sources/setup/configuration.md +++ b/docs/sources/setup/configuration.md @@ -1,8 +1,7 @@ --- -slug: '/configuration' -title: 'Configuration' -menuTitle: Configuration -description: Configuration of the GitHub data source plugin +title: 'Configure Token' +menuTitle: Configure Token +description: Configuring the GitHub personal access token keywords: - data source - github @@ -18,6 +17,18 @@ weight: 102 # Configuration +## Creating a PAT + +2 options + +fine grained +classic + +Split it into 2 sections as tasks + + +### + You will need a **personal access token** to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. Options: From 8b961465cb5abd3f8f71cbb1c15d3744029410b4 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 14:03:49 +0200 Subject: [PATCH 37/61] rename file accordingly --- docs/sources/setup/{authentication.md => datasource.md} | 0 docs/sources/setup/{configuration.md => token.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/sources/setup/{authentication.md => datasource.md} (100%) rename docs/sources/setup/{configuration.md => token.md} (100%) diff --git a/docs/sources/setup/authentication.md b/docs/sources/setup/datasource.md similarity index 100% rename from docs/sources/setup/authentication.md rename to docs/sources/setup/datasource.md diff --git a/docs/sources/setup/configuration.md b/docs/sources/setup/token.md similarity index 100% rename from docs/sources/setup/configuration.md rename to docs/sources/setup/token.md From 95475cecd099334c6ab6bb188266be49f8584df3 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 16:56:28 +0200 Subject: [PATCH 38/61] fixed main page --- docs/sources/_index.md | 8 ++++---- docs/sources/setup/token.md | 29 +++++++++++++++-------------- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index d5ecea4f..9f28c253 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -17,7 +17,7 @@ weight: 10 # GitHub data source plugin for Grafana -The Grafana GitHub data source plugin provides, allow you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. +The Grafana GitHub data source plugin allows you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} @@ -62,9 +62,9 @@ The GitHub data source plugin has the following requirements: - A free [GitHub](https://github.com/) or a [GitHub Enterprise](https://github.com/enterprise) account. - Any of the following Grafana flavours: - - Grafana OSS - - Free or paid [Grafana Cloud](https://grafana.com/pricing/) server - - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server + - Grafana OSS server. + - Free or paid [Grafana Cloud](https://grafana.com/pricing/) server. + - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server. ## Get the most out of the plugin diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index 0847d306..8aa85e97 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -15,21 +15,16 @@ labels: weight: 102 --- -# Configuration +# Configure Token -## Creating a PAT +You will need a **personal access token** to use the plugin. GitHub currently supports two types of personal access tokens: -2 options +1. fine-grained personal access tokens +1. personal access tokens (classic) -fine grained -classic +Read more about [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) -Split it into 2 sections as tasks - - -### - -You will need a **personal access token** to use the plugin. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. +The Grafana GitHub data source plugin works with both. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. Options: @@ -40,11 +35,17 @@ Options: | Repository Access | true | Atleast a single repository is required to access the data | | GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | -Read more about [creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). +## Creating a personal access token (classic) + +This is an example when you want to use the personal access token (classic). -To create a new personal access token, navigate to [Personal access tokens](https://github.com/settings/tokens) and press Generate new token. +1. Login to your GitHub account. +1. Navigate to [Personal access tokens](https://github.com/settings/tokens) and click **Generate new token**. +1. Select the **personal access token (classic)**. +1. Define the permissions which you want to allow. +1. Click **Generate Token**. -## Access token permissions +### personal access token permissions You will need to define the access permissions for your token in order to allow it to access the data. From 853ee0aee1c9a0212fd758d08b3ee4a10d00c5fa Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 16:59:18 +0200 Subject: [PATCH 39/61] fixed setup page --- docs/sources/setup/datasource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index 7edce117..7838e75f 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -1,7 +1,7 @@ --- title: 'Configuring data source' menuTitle: Configure data source -description: Configure the GitHub data source plugin to authenticate to GitHub. +description: Configure the GitHub data source plugin to authenticate to GitHub keywords: - data source - github From 6043f936164b3a2fda565b9494a28b093760c128 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:07:40 +0200 Subject: [PATCH 40/61] fixed installation page --- docs/sources/setup/installation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 03654e88..949d75bc 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -21,9 +21,9 @@ There are multiple ways to install this plugin into your Grafana instance ## Install from plugin catalog -1. Login to Grafana Web UI as *Server Admin* +1. Login to Grafana Web UI as **Server Admin**. 1. Click **Administration** > **Plugins and data** > **Plugins** in the side navigation menu to view all plugins. -1. Type **GitHub** in the Search box +1. Type **GitHub** in the Search box. 1. Click the **All** in the **State** filter option. 1. Click the plugin’s logo. 1. Click Install. @@ -38,7 +38,7 @@ Install the plugin from the [grafana.com plugins page](https://grafana.com/grafa 1. Go to [Releases](https://github.com/grafana/github-datasource/releases/) on the GitHub project page. -1. Find the release you want to install +1. Find the release you want to install. 1. Download the release by clicking the release asset called `grafana-github-datasource-.zip`. You may need to un-collapse the **Assets** section to see it. @@ -61,11 +61,11 @@ Install the plugin from the [grafana.com plugins page](https://grafana.com/grafa ## Install using grafana-cli -If you are using grafana-cli, execute the following command to install the latest published version of the plugin +If you are using `grafana-cli`, execute the following command to install the latest published version of the plugin: -1. Login to your machine as root user. +1. Login to your machine as `root` user. -1. In Linux/macOS, ypen your terminal and write the command: +1. In Linux/macOS, open your terminal and write the command: ```bash grafana-cli plugins install grafana-github-datasource From 0f20a065e4c525a41e96de2646c1a9c1f6739628 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:10:29 +0200 Subject: [PATCH 41/61] fixed token page --- docs/sources/setup/token.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index 8aa85e97..f9716ae7 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -22,7 +22,7 @@ You will need a **personal access token** to use the plugin. GitHub currently su 1. fine-grained personal access tokens 1. personal access tokens (classic) -Read more about [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +Read more about [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). The Grafana GitHub data source plugin works with both. Below is a table that indicates what minimum requirements must be matched before the plugin can be used. @@ -65,6 +65,6 @@ For GitHub projects: - `read:org` - `read:project` -An extra setting is required for private repositories +An extra setting is required for private repositories: - `repo (Full control of private repositories)` From f1703e1dcbe10f2472277134e625e18c73cb3830 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:19:07 +0200 Subject: [PATCH 42/61] fixed token page --- docs/sources/setup/datasource.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index 7838e75f..7224fa42 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -15,7 +15,7 @@ labels: weight: 103 --- -# Configure Data source +# Configure data source 1. After creating the **personal access token** in GitHub, navigate into Grafana and click on the menu option on the top left. @@ -23,14 +23,16 @@ weight: 103 1. Click on the GitHub data source plugin which you have installed. -1. Go to its settings tab and at the bottom, paste the GitHub token which you have created above. +1. Go to its settings tab and at the bottom, you will find the **Connection** section. + +1. Paste the personal access token. ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) 1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". ## For GitHub Enterprise -If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section (as show in the image of the **step 4** describe above) and paste the URL of your GitHub Enterprise. +If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section (as show in the image of the **step 4** described above) and paste the URL of your GitHub Enterprise. {{< admonition type="tip" >}} If you see errors, check the Grafana logs for troubleshooting. From cd3ab418e70deba7c6a5e6e3caf802692aafe51f Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:20:44 +0200 Subject: [PATCH 43/61] fixed provisioning page --- docs/sources/setup/provisioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index c4f80c2e..50047030 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -21,7 +21,7 @@ You can define and configure the GitHub data source in YAML files with Grafana p **Example** -Here is an example to provision the Data source while using the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) +Here is an example to provision the data source while using the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) ```yaml promop: From 0304e28d0e92327e96055a17dc0ffbc9d30dfff8 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:22:35 +0200 Subject: [PATCH 44/61] fixed variable and macro page --- docs/sources/variables-and-macros/macros.md | 2 +- docs/sources/variables-and-macros/variables.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index 322633f8..fa906b8d 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -18,7 +18,7 @@ weight: 202 # Macros -A macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible and adaptable to changing conditions. It's important to note that while not all data source plugins have macros as it availability and implementation depends on the specific design and capabilities of each plugin. +A Macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible and adaptable to changing conditions. It's important to note that while not all data source plugins have macros as it availability and implementation depends on the specific design and capabilities of each plugin. The GitHub data source plugin do support the macro feature and you can use the following macros in your queries: diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index f0c9795b..a2d73acb 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -18,7 +18,7 @@ weight: 201 # Variables -[Variable](https://grafana.com/docs/grafana/latest/variables/) is a placeholder for a value that can be used in queries for a dashboard. +A [Variable](https://grafana.com/docs/grafana/latest/variables/) is a placeholder for a value that can be used in queries for a dashboard. Variables allow you to create more interactive and dynamic dashboards by replacing hard-coded values with dynamic options. They are displayed as dropdown lists at the top of the dashboard, making it easy to change the data being displayed. @@ -30,4 +30,4 @@ Here is an example of creating a dashboard variable: You can reference them inside queries, allowing users to configure parameters such as `Query` or `Repository`. -![Using variables inside queries](/media/docs/grafana/data-sources/github/using-variables.png) \ No newline at end of file +![Using variables inside queries](/media/docs/grafana/data-sources/github/using-variables.png) From be9fb11e895d9085c6d11169f813d2d39216529f Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:43:47 +0200 Subject: [PATCH 45/61] fixed examples page --- docs/sources/examples/_index.md | 18 ++++++------------ docs/sources/variables-and-macros/macros.md | 2 +- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 7b517bc0..bdba36de 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -31,23 +31,17 @@ There are two ways to use the pre-configure dashboards: ### Importing from the official Website -For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard). +Import the dashboards form the official page [located here](https://grafana.com/grafana/dashboards/14000). -The sample dashboard can be obtained from either of two places. - -- Importing from the Grafana dashboards page [located here](https://grafana.com/grafana/dashboards/14000) +For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) and replace the ID with `1400`. ### Importing from the Grafana server WebUI -- From the GitHub data source configuration page: - - 1. Navigate to "Connections" and then click "Data sources". - 2. Select the GitHub plugin and click the "Dashboards" tab. - 3. Click "Import". +From the GitHub data source configuration page: - {{% admonition type="note" %}} - If loading it from this repository, open Grafana and click "Import Dashboard". Copy the JSON in `./src/dashboards/dashboard.json`, and paste it into the "Import via panel json" box. - {{% /admonition %}} +1. Navigate to **Connections** and then click **Data sources**. +1. Select the GitHub plugin and click the **Dashboards** tab. +1. Click **Import**. ## 2. Play demo diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index fa906b8d..801fbed3 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -26,4 +26,4 @@ The GitHub data source plugin do support the macro feature and you can use the f | ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | multiVar | `$__multiVar(prefix,$var)` | Expands a multi value variable into github query string | `$__multiVar(label,$labels)` will expand into `label:first-label label:second-label` | | | | When using **all** in multi variable, use **\*** as custom all value | | -| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | \ No newline at end of file +| day | `$__toDay(diff)` | Returns the day according to UTC time, a difference in days can be added | `created:$__toDay(-7)` on 2022-01-17 will expand into `created:2022-01-10` | From 7a21747dd23cb12c859d960de6f13b450dd58c1f Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 17:50:52 +0200 Subject: [PATCH 46/61] run prettier --- docs/sources/setup/datasource.md | 12 ++++++------ docs/sources/setup/token.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index 7224fa42..c70f6866 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -34,10 +34,10 @@ weight: 103 If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section (as show in the image of the **step 4** described above) and paste the URL of your GitHub Enterprise. - {{< admonition type="tip" >}} - If you see errors, check the Grafana logs for troubleshooting. - {{< /admonition >}} +{{< admonition type="tip" >}} +If you see errors, check the Grafana logs for troubleshooting. +{{< /admonition >}} - {{< admonition type="note" >}} - If you are using GitHub OAuth on Grafana, then it is not possible that the users to make requests with their individual GitHub accounts instead of a shared `access_token`. Please refer to [this issue](https://github.com/grafana/grafana/issues/26023) in the Grafana project. - {{< /admonition >}} +{{< admonition type="note" >}} +If you are using GitHub OAuth on Grafana, then it is not possible that the users to make requests with their individual GitHub accounts instead of a shared `access_token`. Please refer to [this issue](https://github.com/grafana/grafana/issues/26023) in the Grafana project. +{{< /admonition >}} diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index f9716ae7..88c71fac 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -28,12 +28,12 @@ The Grafana GitHub data source plugin works with both. Below is a table that ind Options: -| Setting | Required | Description | -| --------------------- | -------- |-------------------------------------------------------| -| Access token | true | This is required to allow plugin to connect to GitHub | -| Default Organization | false | Only if you want to set a specfic organization as a default selection while creating Dashboards | -| Repository Access | true | Atleast a single repository is required to access the data | -| GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | +| Setting | Required | Description | +| --------------------- | -------- | ----------------------------------------------------------------------------------------------- | +| Access token | true | This is required to allow plugin to connect to GitHub | +| Default Organization | false | Only if you want to set a specfic organization as a default selection while creating Dashboards | +| Repository Access | true | Atleast a single repository is required to access the data | +| GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | ## Creating a personal access token (classic) From 3c48b15d1d2873afffd26a27e57ed00b62ecb34b Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Tue, 16 Jul 2024 19:56:06 +0200 Subject: [PATCH 47/61] Apply suggestions from code review thanks for the typo fix :) Co-authored-by: Sriram <153843+yesoreyeram@users.noreply.github.com> --- docs/sources/examples/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index bdba36de..74f44bcd 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -31,7 +31,7 @@ There are two ways to use the pre-configure dashboards: ### Importing from the official Website -Import the dashboards form the official page [located here](https://grafana.com/grafana/dashboards/14000). +Import the dashboards from the official page [located here](https://grafana.com/grafana/dashboards/14000). For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) and replace the ID with `1400`. From 70e6ab69866b9978d6b2bac76180579238afaf96 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 09:32:02 +0200 Subject: [PATCH 48/61] removed outdated info --- docs/sources/setup/token.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index 88c71fac..d473e87d 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -31,8 +31,6 @@ Options: | Setting | Required | Description | | --------------------- | -------- | ----------------------------------------------------------------------------------------------- | | Access token | true | This is required to allow plugin to connect to GitHub | -| Default Organization | false | Only if you want to set a specfic organization as a default selection while creating Dashboards | -| Repository Access | true | Atleast a single repository is required to access the data | | GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | ## Creating a personal access token (classic) From 128114173ef52eeb557d3ec98307e0f2a13f0285 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 14:30:59 +0200 Subject: [PATCH 49/61] Apply suggestions from code review Looks good!! Co-authored-by: Jack Baldry --- docs/sources/_index.md | 28 +++++----- docs/sources/annotations/_index.md | 2 +- docs/sources/setup/_index.md | 2 + docs/sources/setup/datasource.md | 8 +-- docs/sources/setup/installation.md | 54 +++++++++---------- docs/sources/setup/provisioning.md | 15 ++---- docs/sources/setup/token.md | 12 ++--- docs/sources/variables-and-macros/_index.md | 13 ++--- docs/sources/variables-and-macros/macros.md | 8 +-- .../sources/variables-and-macros/variables.md | 5 +- 10 files changed, 71 insertions(+), 76 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 9f28c253..385c8a00 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -17,14 +17,14 @@ weight: 10 # GitHub data source plugin for Grafana -The Grafana GitHub data source plugin allows you to track and analyze GitHub data directly within Grafana, providing insights and visualizations for your GitHub repositories and projects. +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. {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/d/cdgx261sa1ypsa/3-single-repo-with-override-examples" >}} -The plugin provide the features listed below: - ## Query types +The plugin supports the following query types: + - Commits - Issues - Contributors @@ -43,17 +43,21 @@ The plugin provide the features listed below: ## Supported features +With the plugin you can: + - Visualize queries -- Template variables -- Annotations -- Query caching +- Use template variables +- Configure Annotations +- Cache queries ## Caching Caching on this plugin is always enabled. {{< admonition type="note" >}} -Sometimes it may take up to 5 minutes as we have aggressive caching enabled due to [GitHub's rate limiting](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28) policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily. +To work around [GitHub's rate limiting](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28), the plugin caches requests aggressively. + +This can mean that it takes up to five minutes for a new pull request, commit, or issue to show up in a query. {{< /admonition >}} ## Requirements @@ -61,10 +65,10 @@ Sometimes it may take up to 5 minutes as we have aggressive caching enabled due The GitHub data source plugin has the following requirements: - A free [GitHub](https://github.com/) or a [GitHub Enterprise](https://github.com/enterprise) account. -- Any of the following Grafana flavours: +- Any of the following Grafana editions: - Grafana OSS server. - - Free or paid [Grafana Cloud](https://grafana.com/pricing/) server. - - An [activated on-prem Grafana Enterprise](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/) server. + - A [Grafana Cloud](https://grafana.com/pricing/) stack. + - An on-premise Grafana Enterprise server with an [activated license](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/). ## Get the most out of the plugin @@ -72,9 +76,9 @@ The GitHub data source plugin has the following requirements: - Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/) - Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/) -## Reporting issues +## Report issues -Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs and feature requests. +Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs, and feature requests. ### Further reading diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index d9bfaf3a..e385e863 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -1,7 +1,7 @@ --- title: 'Annotations' menuTitle: Annotations -description: Using annotations for the GitHub data source plugin +description: Learn about annotations for the GitHub data source plugin for Grafana keywords: - data source - github diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md index f45075a4..db883784 100644 --- a/docs/sources/setup/_index.md +++ b/docs/sources/setup/_index.md @@ -17,4 +17,6 @@ weight: 100 # Set up the GitHub data source plugin +To set up the GitHub data source plugin for Grafana, refer to the following topics: + {{< section menuTitle="true" withDescriptions="true" >}} diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index c70f6866..2047b03c 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -1,6 +1,6 @@ --- -title: 'Configuring data source' -menuTitle: Configure data source +title: Configure the GitHub data source plugin for Grafana +menuTitle: Configure description: Configure the GitHub data source plugin to authenticate to GitHub keywords: - data source @@ -15,7 +15,7 @@ labels: weight: 103 --- -# Configure data source +# Configure the GitHub data source plugin for Grafana 1. After creating the **personal access token** in GitHub, navigate into Grafana and click on the menu option on the top left. @@ -39,5 +39,5 @@ If you see errors, check the Grafana logs for troubleshooting. {{< /admonition >}} {{< admonition type="note" >}} -If you are using GitHub OAuth on Grafana, then it is not possible that the users to make requests with their individual GitHub accounts instead of a shared `access_token`. Please refer to [this issue](https://github.com/grafana/grafana/issues/26023) in the Grafana project. +It's not yet possible to use the GitHub OAuth 2.0 for authenticating Grafana users to make requests with their individual GitHub accounts instead of the data source personal access token. {{< /admonition >}} diff --git a/docs/sources/setup/installation.md b/docs/sources/setup/installation.md index 949d75bc..08db12de 100644 --- a/docs/sources/setup/installation.md +++ b/docs/sources/setup/installation.md @@ -1,7 +1,7 @@ --- -title: 'Installation' -menuTitle: Installation -description: Install the GitHub data source plugin +title: Install the GitHub data source plugin for Grafana +menuTitle: Install +description: Learn how to install the GitHub data source plugin for Grafana keywords: - data source - github @@ -15,18 +15,18 @@ labels: weight: 101 --- -# Install the GitHub data source plugin +# Install the GitHub data source plugin for Grafana -There are multiple ways to install this plugin into your Grafana instance +You can any of the following sets of steps to install the GitHub data source plugin for Grafana. ## Install from plugin catalog -1. Login to Grafana Web UI as **Server Admin**. +1. Sign in to Grafana as a server administrator. 1. Click **Administration** > **Plugins and data** > **Plugins** in the side navigation menu to view all plugins. 1. Type **GitHub** in the Search box. 1. Click the **All** in the **State** filter option. 1. Click the plugin’s logo. -1. Click Install. +1. Click **Install**. Find more information about the [plugin catalog](https://grafana.com/docs/grafana/latest/administration/plugin-management/#plugin-catalog). @@ -40,24 +40,24 @@ Install the plugin from the [grafana.com plugins page](https://grafana.com/grafa 1. Find the release you want to install. -1. Download the release by clicking the release asset called `grafana-github-datasource-.zip`. You may need to un-collapse the **Assets** section to see it. +1. Download the release by clicking the release asset called `grafana-github-datasource-.zip`. You may need to un-collapse the **Assets** section to see it. 1. Unarchive the plugin into the Grafana plugins directory: - In Linux/macOS, you can use the following command to extract the plugin: + On Linux or macOS, run the following commands to extract the plugin: ```bash - unzip grafana-github-datasource-.zip + unzip grafana-github-datasource-.zip mv grafana-github-datasource /var/lib/grafana/plugins ``` - In Windows, you can use the following command to extract the plugin: + On Windows, run the following command to extract the plugin: - ```shell - Expand-Archive -Path grafana-github-datasource-.zip -DestinationPath C:\grafana\data\plugins + ```powershell + Expand-Archive -Path grafana-github-datasource-.zip -DestinationPath C:\grafana\data\plugins ``` -1. Then restart Grafana. +1. Restart Grafana. ## Install using grafana-cli @@ -65,13 +65,13 @@ If you are using `grafana-cli`, execute the following command to install the lat 1. Login to your machine as `root` user. -1. In Linux/macOS, open your terminal and write the command: +1. On Linux or macOS, open your terminal and run the following command: ```bash grafana-cli plugins install grafana-github-datasource ``` - Similarly, if you are using Windows machine, use the following command: + On Windows, run the following command: ```shell grafana-cli.exe plugins install grafana-github-datasource @@ -81,24 +81,20 @@ If you are using `grafana-cli`, execute the following command to install the lat ### Install custom version -If you need custom version of the plugin from github, you can install using the following command: +If you need custom version of the plugin from GitHub, you can install it by running the following command: ```bash grafana-cli --pluginUrl plugins install grafana-github-datasource ``` -**Example:** - -1. In Linux/macOS: - - ```bash - grafana-cli --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource - ``` +For example, to install version 1.6.0 of the plugin on Linux or macOS: -1. In Windows: +```bash +grafana-cli --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource +``` - ```shell - grafana-cli.exe --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource - ``` +Or to install version 1.6.0 of the plugin on Windows: -1. Then restart Grafana. +```powershell +grafana-cli.exe --pluginUrl https://github.com/grafana/github-datasource/releases/download/v1.6.0/grafana-github-datasource-1.6.0.zip plugins install grafana-github-datasource +``` diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index 50047030..a8780dca 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -21,7 +21,7 @@ You can define and configure the GitHub data source in YAML files with Grafana p **Example** -Here is an example to provision the data source while using the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) +The following YAML snippet can be used to provision the GitHub data source for Grafana if you are using [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator): ```yaml promop: @@ -30,14 +30,7 @@ promop: - name: GitHub Repo Insights type: grafana-github-datasource jsonData: - owner: ’’ - repository: ’’ + owner: ’’ + repository: ’’ secureJsonData: - accessToken: ’’ -``` - -Replace; - -- _``_: name of the owner who owns the repository -- _``_: name of the repository to get the data -- _``_: your GitHub personal access token + accessToken: ’’ diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index d473e87d..c52f1dbf 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -1,7 +1,7 @@ --- -title: 'Configure Token' -menuTitle: Configure Token -description: Configuring the GitHub personal access token +title: Create a GitHub personal access token +menuTitle: Create a personal access token +description: Create a GitHub personal access token keywords: - data source - github @@ -15,9 +15,9 @@ labels: weight: 102 --- -# Configure Token +# Create a GitHub personal access token -You will need a **personal access token** to use the plugin. GitHub currently supports two types of personal access tokens: +You will need a _personal access token_ to use the plugin. GitHub currently supports two types of personal access tokens: 1. fine-grained personal access tokens 1. personal access tokens (classic) @@ -43,7 +43,7 @@ This is an example when you want to use the personal access token (classic). 1. Define the permissions which you want to allow. 1. Click **Generate Token**. -### personal access token permissions +### Permissions You will need to define the access permissions for your token in order to allow it to access the data. diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index 10d1d413..aaa083ef 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -1,7 +1,7 @@ --- -title: 'Variables & macros' -menuTitle: Variables & macros -description: Variables & macros +title: Variables and macros +menuTitle: Variables and macros +description: Learn about variables and macros you can use in the GitHub data source plugin for Grafana keywords: - data source - github @@ -15,7 +15,8 @@ labels: weight: 200 --- -# Variables & macros +# Variables and macros -- [Variables](./variables) -- [Macros](./macros) +To learn more about variables and macros you can use in the GitHub data source plugin for Grafana, refer to the following topics: + +{{< section menuTitle="true" withDescriptions="true" >}} diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index 801fbed3..a215b9c2 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -1,8 +1,7 @@ --- -slug: '/macros' title: 'Macros' menuTitle: Macros -description: Using macros for the GitHub data source plugin +description: Learn about the macros you can use in the GitHub data source plugin for Grafana keywords: - data source - github @@ -18,9 +17,10 @@ weight: 202 # Macros -A Macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible and adaptable to changing conditions. It's important to note that while not all data source plugins have macros as it availability and implementation depends on the specific design and capabilities of each plugin. +A macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. +They help make your queries more flexible. -The GitHub data source plugin do support the macro feature and you can use the following macros in your queries: +The GitHub data source plugin for Grafana supports the following macros: | Macro name | Syntax | Description | Example | | ---------- | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index a2d73acb..0447fa17 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -1,8 +1,7 @@ --- -slug: '/variables' title: 'Variables' menuTitle: Variables -description: Using variables for the GitHub data source plugin +description: Learn about the variables you can use in the GitHub data source plugin for Grafana keywords: - data source - github @@ -18,7 +17,7 @@ weight: 201 # Variables -A [Variable](https://grafana.com/docs/grafana/latest/variables/) is a placeholder for a value that can be used in queries for a dashboard. +A [variable](https://grafana.com/docs/grafana/latest/variables/) is a placeholder for a value that you can use in dashboard queries. Variables allow you to create more interactive and dynamic dashboards by replacing hard-coded values with dynamic options. They are displayed as dropdown lists at the top of the dashboard, making it easy to change the data being displayed. From a48226604023bbf75c4c1b38227ebdcb0edbe534 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 14:39:03 +0200 Subject: [PATCH 50/61] made requested changes --- docs/sources/_index.md | 9 +++------ docs/sources/setup/datasource.md | 10 ++-------- docs/sources/setup/token.md | 2 +- 3 files changed, 6 insertions(+), 15 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 385c8a00..01b9c97f 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -62,7 +62,7 @@ This can mean that it takes up to five minutes for a new pull request, commit, o ## Requirements -The GitHub data source plugin has the following requirements: +To use the GitHub data source plugin, you will need: - A free [GitHub](https://github.com/) or a [GitHub Enterprise](https://github.com/enterprise) account. - Any of the following Grafana editions: @@ -70,6 +70,8 @@ The GitHub data source plugin has the following requirements: - A [Grafana Cloud](https://grafana.com/pricing/) stack. - An on-premise Grafana Enterprise server with an [activated license](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/). +## Getting Started + ## Get the most out of the plugin - Add [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations/) @@ -79,8 +81,3 @@ The GitHub data source plugin has the following requirements: ## Report issues Use the [official GitHub repository](https://github.com/grafana/github-datasource/issues) to report issues, bugs, and feature requests. - -### Further reading - -- [GitHub v4 client library](https://github.com/shurcooL/githubv4) -- [Manage personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index 2047b03c..5d79f445 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -28,16 +28,10 @@ weight: 103 1. Paste the personal access token. ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) -1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". - -## For GitHub Enterprise + (Optional): If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section and paste the URL of your GitHub Enterprise. -If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section (as show in the image of the **step 4** described above) and paste the URL of your GitHub Enterprise. +1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". {{< admonition type="tip" >}} If you see errors, check the Grafana logs for troubleshooting. {{< /admonition >}} - -{{< admonition type="note" >}} -It's not yet possible to use the GitHub OAuth 2.0 for authenticating Grafana users to make requests with their individual GitHub accounts instead of the data source personal access token. -{{< /admonition >}} diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index c52f1dbf..bb86285c 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -47,7 +47,7 @@ This is an example when you want to use the personal access token (classic). You will need to define the access permissions for your token in order to allow it to access the data. -Here is a list of the required minimum permissions defined below: +The following lists include the required permissions for the access token: For all repositories: From b1ade81a2a71f498fb7a0e3b31137966e50720b0 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 14:53:40 +0200 Subject: [PATCH 51/61] improved the examples section --- docs/sources/examples/_index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 74f44bcd..6e4b44f9 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -33,15 +33,17 @@ There are two ways to use the pre-configure dashboards: Import the dashboards from the official page [located here](https://grafana.com/grafana/dashboards/14000). -For documentation on importing dashboards, check out the documentation on [grafana.com](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) and replace the ID with `1400`. +For instructions on how to import dashboards in Grafana, see [Import a dashboard](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) and replace the ID with `1400`. ### Importing from the Grafana server WebUI -From the GitHub data source configuration page: +To view a list of pre-made GitHub dashboards do the following: -1. Navigate to **Connections** and then click **Data sources**. -1. Select the GitHub plugin and click the **Dashboards** tab. -1. Click **Import**. +1. Go to **Connections** in the sidebar menu. +1. Under Connections, click **Data sources**. +1. Type `GitHub` in the search bar and select the GitHub data source. +1. Go to the **Dashboards** tab to view a list of pre-made dashboards. +1. Click **Import** to import the pre-made dashboard. ## 2. Play demo From 7083bc5e90daf7a047e84978bfa3c7414adec6db Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 14:57:59 +0200 Subject: [PATCH 52/61] fixed example page metadata --- docs/sources/examples/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 6e4b44f9..9f9921a1 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -1,7 +1,7 @@ --- -title: 'Examples dashboards' -menuTitle: Examples dashboards -description: Examples dashboards +title: Using Example dashboards for the GitHub data source plugin +menuTitle: Example dashboards +description: Learn how to import pre-made example dashboards keywords: - data source - github From 7905ca20a06c0fd72cf91bd72d0a196af76fd63f Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 14:58:31 +0200 Subject: [PATCH 53/61] run prettier --- docs/sources/setup/provisioning.md | 1 + docs/sources/setup/token.md | 8 ++++---- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index a8780dca..169ee265 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -34,3 +34,4 @@ promop: repository: ’’ secureJsonData: accessToken: ’’ +``` diff --git a/docs/sources/setup/token.md b/docs/sources/setup/token.md index bb86285c..209fec83 100644 --- a/docs/sources/setup/token.md +++ b/docs/sources/setup/token.md @@ -28,10 +28,10 @@ The Grafana GitHub data source plugin works with both. Below is a table that ind Options: -| Setting | Required | Description | -| --------------------- | -------- | ----------------------------------------------------------------------------------------------- | -| Access token | true | This is required to allow plugin to connect to GitHub | -| GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | +| Setting | Required | Description | +| --------------------- | -------- | ----------------------------------------------------- | +| Access token | true | This is required to allow plugin to connect to GitHub | +| GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account | ## Creating a personal access token (classic) From 0a34206de604e2ed2f224bad14bc6b9fc31e71e1 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 21:15:19 +0200 Subject: [PATCH 54/61] Update docs/sources/_index.md Co-authored-by: Jack Baldry --- docs/sources/_index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 01b9c97f..d91a483e 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -72,6 +72,11 @@ To use the GitHub data source plugin, you will need: ## Getting Started +## Get started + +To start using the plugin, you need to generate an access token, then install and configure the plugin. +To do this, refer to [Setup](LINK). + ## Get the most out of the plugin - Add [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations/) From dc1d56b0b33839a407e4bba063f798016de99e01 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Wed, 17 Jul 2024 21:56:33 +0200 Subject: [PATCH 55/61] fixed the Get Started section --- docs/sources/_index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index d91a483e..07680e9b 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -70,12 +70,12 @@ To use the GitHub data source plugin, you will need: - A [Grafana Cloud](https://grafana.com/pricing/) stack. - An on-premise Grafana Enterprise server with an [activated license](https://grafana.com/docs/grafana/latest/enterprise/license/activate-license/). -## Getting Started - ## Get started -To start using the plugin, you need to generate an access token, then install and configure the plugin. -To do this, refer to [Setup](LINK). +- To start using the plugin, you need to generate an access token, then install and configure the plugin. To do this, refer to [Setup](/docs/plugins//github-datasource/setup). +- To use variable and macros, for creating a dynamic dashboard, refer to [Variables and Macros](/docs/plugins//github-datasource/variables-and-macros). +- To annotate the data by displaying the GitHub resources on the dashboard, refer to [Annotations](/docs/plugins//github-datasource/annotations/). +- Try out some example pre-configured dashboard either by importing them or view live on play, refer to [Examples](/docs/plugins//github-datasource/examples/). ## Get the most out of the plugin From 50a00b61ca9e6956a6f9cb85f3caac0b9c2e74e4 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Thu, 18 Jul 2024 11:40:58 +0200 Subject: [PATCH 56/61] fixed get started links --- docs/sources/_index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 07680e9b..0b298ff8 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -72,10 +72,10 @@ To use the GitHub data source plugin, you will need: ## Get started -- To start using the plugin, you need to generate an access token, then install and configure the plugin. To do this, refer to [Setup](/docs/plugins//github-datasource/setup). -- To use variable and macros, for creating a dynamic dashboard, refer to [Variables and Macros](/docs/plugins//github-datasource/variables-and-macros). -- To annotate the data by displaying the GitHub resources on the dashboard, refer to [Annotations](/docs/plugins//github-datasource/annotations/). -- Try out some example pre-configured dashboard either by importing them or view live on play, refer to [Examples](/docs/plugins//github-datasource/examples/). +- To start using the plugin, you need to generate an access token, then install and configure the plugin. To do this, refer to [Setup](./setup). +- To use variable and macros, for creating a dynamic dashboard, refer to [Variables and Macros](./variables-and-macros). +- To annotate the data by displaying the GitHub resources on the dashboard, refer to [Annotations](./annotations/). +- Try out some example pre-configured dashboard either by importing them or view live on play, refer to [Examples](./examples/). ## Get the most out of the plugin From 503b5161b74425506259c53023b6986054b66dbf Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Fri, 19 Jul 2024 12:06:47 +0200 Subject: [PATCH 57/61] fixed metadata on all pages and fixed sample dashboard page --- docs/sources/_index.md | 4 ++-- docs/sources/examples/_index.md | 20 +++++++++---------- docs/sources/setup/_index.md | 4 ++-- docs/sources/setup/datasource.md | 2 +- docs/sources/setup/provisioning.md | 4 ++-- docs/sources/variables-and-macros/_index.md | 4 ++-- docs/sources/variables-and-macros/macros.md | 4 ++-- .../sources/variables-and-macros/variables.md | 4 ++-- 8 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 0b298ff8..27cabf8d 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -1,4 +1,6 @@ --- +title: GitHub data source plugin for Grafana +menuTitle: GitHub data source description: The GitHub data source lets you visualize GitHub data in Grafana dashboards. keywords: - data source @@ -10,8 +12,6 @@ labels: - oss - enterprise - cloud -menuTitle: GitHub data source -title: GitHub data source plugin for Grafana weight: 10 --- diff --git a/docs/sources/examples/_index.md b/docs/sources/examples/_index.md index 9f9921a1..588805f7 100644 --- a/docs/sources/examples/_index.md +++ b/docs/sources/examples/_index.md @@ -1,6 +1,6 @@ --- -title: Using Example dashboards for the GitHub data source plugin -menuTitle: Example dashboards +title: Create a sample dashboards for the Grafana GitHub data source plugin +menuTitle: Sample dashboards description: Learn how to import pre-made example dashboards keywords: - data source @@ -15,16 +15,16 @@ labels: weight: 500 --- -# Example dashboard +# Create a sample dashboards the GitHub data source plugin using Grafana -There are multiple ways to use some of the examples dashboards that you can use for your use case. +This page explains how you can create a sample dashboard in Grafana to get started with the GitHub data source plugin. You can obtain these sample dashboards by: -1. Using pre-configured dashboards -1. Using play demo +- Using pre-configured dashboards +- Using play demo -## 1. Using pre-configure dashboards +## Using pre-configure dashboards -There are two ways to use the pre-configure dashboards: +The pre-configured dashboards are ready-to-use and you only need to import them inside your Grafana server. There are two ways to use the pre-configure dashboards: - Importing from the official Website - Importing from the Grafana server WebUI @@ -45,8 +45,8 @@ To view a list of pre-made GitHub dashboards do the following: 1. Go to the **Dashboards** tab to view a list of pre-made dashboards. 1. Click **Import** to import the pre-made dashboard. -## 2. Play demo +## Play demo -You can also take a look at the live dashboards on Grafana Play. +The Play demo dashboards prvoide a reference, allows you to create your own custom dashboards. {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github" >}} diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md index db883784..6c4329dc 100644 --- a/docs/sources/setup/_index.md +++ b/docs/sources/setup/_index.md @@ -1,5 +1,5 @@ --- -title: Set up the GitHub data source plugin +title: Set up the GitHub data source plugin for Grafana menuTitle: Setup description: Learn how to install and configure the GitHub data source plugin. keywords: @@ -15,7 +15,7 @@ labels: weight: 100 --- -# Set up the GitHub data source plugin +# Set up the GitHub data source plugin for Grafana To set up the GitHub data source plugin for Grafana, refer to the following topics: diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index 5d79f445..cd8b45d2 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -28,7 +28,7 @@ weight: 103 1. Paste the personal access token. ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) - (Optional): If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section and paste the URL of your GitHub Enterprise. + (*Optional*): If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section and paste the URL of your GitHub Enterprise. 1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". diff --git a/docs/sources/setup/provisioning.md b/docs/sources/setup/provisioning.md index 169ee265..bbe3659f 100644 --- a/docs/sources/setup/provisioning.md +++ b/docs/sources/setup/provisioning.md @@ -1,5 +1,5 @@ --- -title: 'Provisioning' +title: Provisioning the Github data source in Grafana menuTitle: Provisioning description: Provisioning the GitHub data source plugin keywords: @@ -15,7 +15,7 @@ labels: weight: 104 --- -# Provisioning +# Provisioning the Github data source in Grafana You can define and configure the GitHub data source in YAML files with Grafana provisioning. For more information about provisioning a data source, and for available configuration options, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources). diff --git a/docs/sources/variables-and-macros/_index.md b/docs/sources/variables-and-macros/_index.md index aaa083ef..edc33ee2 100644 --- a/docs/sources/variables-and-macros/_index.md +++ b/docs/sources/variables-and-macros/_index.md @@ -1,5 +1,5 @@ --- -title: Variables and macros +title: Use GitHub data source variables and macros in Grafana menuTitle: Variables and macros description: Learn about variables and macros you can use in the GitHub data source plugin for Grafana keywords: @@ -15,7 +15,7 @@ labels: weight: 200 --- -# Variables and macros +# Use GitHub data source variables and macros in Grafana To learn more about variables and macros you can use in the GitHub data source plugin for Grafana, refer to the following topics: diff --git a/docs/sources/variables-and-macros/macros.md b/docs/sources/variables-and-macros/macros.md index a215b9c2..ebee6ee4 100644 --- a/docs/sources/variables-and-macros/macros.md +++ b/docs/sources/variables-and-macros/macros.md @@ -1,5 +1,5 @@ --- -title: 'Macros' +title: Use macros with GitHub data source plugin for Grafana menuTitle: Macros description: Learn about the macros you can use in the GitHub data source plugin for Grafana keywords: @@ -15,7 +15,7 @@ labels: weight: 202 --- -# Macros +# Use macros with GitHub data source plugin for Grafana A macro is a feature that allows you to simplify the syntax and add dynamic parts to your queries. They help make your queries more flexible. diff --git a/docs/sources/variables-and-macros/variables.md b/docs/sources/variables-and-macros/variables.md index 0447fa17..a4c0e0dc 100644 --- a/docs/sources/variables-and-macros/variables.md +++ b/docs/sources/variables-and-macros/variables.md @@ -1,5 +1,5 @@ --- -title: 'Variables' +title: Create variable with GitHub data source plugin for Grafana menuTitle: Variables description: Learn about the variables you can use in the GitHub data source plugin for Grafana keywords: @@ -15,7 +15,7 @@ labels: weight: 201 --- -# Variables +# Create variable with GitHub data source plugin for Grafana A [variable](https://grafana.com/docs/grafana/latest/variables/) is a placeholder for a value that you can use in dashboard queries. From 9ba77cba329c83608341ff6d3448cdfdee2e79a7 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Fri, 19 Jul 2024 12:07:54 +0200 Subject: [PATCH 58/61] fixed minor changes --- docs/sources/annotations/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/annotations/_index.md b/docs/sources/annotations/_index.md index e385e863..7fa0cd2b 100644 --- a/docs/sources/annotations/_index.md +++ b/docs/sources/annotations/_index.md @@ -1,5 +1,5 @@ --- -title: 'Annotations' +title: Create annotations with GitHub data source plugin for Grafana menuTitle: Annotations description: Learn about annotations for the GitHub data source plugin for Grafana keywords: @@ -15,7 +15,7 @@ labels: weight: 400 --- -# Annotations +# Create annotations with GitHub data source plugin for Grafana [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations) let you extract data from a data source and use it to annotate a dashboard. From f646c6bd1fca5c187512a7477e424ef15dfbef02 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Fri, 19 Jul 2024 12:09:08 +0200 Subject: [PATCH 59/61] run prettier --- docs/sources/setup/datasource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/setup/datasource.md b/docs/sources/setup/datasource.md index cd8b45d2..75178172 100644 --- a/docs/sources/setup/datasource.md +++ b/docs/sources/setup/datasource.md @@ -28,7 +28,7 @@ weight: 103 1. Paste the personal access token. ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png) - (*Optional*): If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section and paste the URL of your GitHub Enterprise. + (_Optional_): If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section and paste the URL of your GitHub Enterprise. 1. Click **Save & Test** button and you should see a confirmation dialog box that says "Data source is working". From 813534c63ccfeb52c92629c32b050a4433a36bee Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Fri, 19 Jul 2024 12:27:03 +0200 Subject: [PATCH 60/61] renamed file and minor changes --- docs/sources/_index.md | 2 +- docs/sources/{examples => sample-dashboards}/_index.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/sources/{examples => sample-dashboards}/_index.md (100%) diff --git a/docs/sources/_index.md b/docs/sources/_index.md index 27cabf8d..00e7634b 100644 --- a/docs/sources/_index.md +++ b/docs/sources/_index.md @@ -75,7 +75,7 @@ To use the GitHub data source plugin, you will need: - To start using the plugin, you need to generate an access token, then install and configure the plugin. To do this, refer to [Setup](./setup). - To use variable and macros, for creating a dynamic dashboard, refer to [Variables and Macros](./variables-and-macros). - To annotate the data by displaying the GitHub resources on the dashboard, refer to [Annotations](./annotations/). -- Try out some example pre-configured dashboard either by importing them or view live on play, refer to [Examples](./examples/). +- To quickly visualize GitHub data in Grafana, refer to [Sample dashboards](./sample-dashboards/). ## Get the most out of the plugin diff --git a/docs/sources/examples/_index.md b/docs/sources/sample-dashboards/_index.md similarity index 100% rename from docs/sources/examples/_index.md rename to docs/sources/sample-dashboards/_index.md From 9304ac70e6dc119bc36033713ee0df5c9c097e64 Mon Sep 17 00:00:00 2001 From: Usman Ahmad Date: Mon, 22 Jul 2024 13:43:54 +0200 Subject: [PATCH 61/61] Apply suggestions from code review Thanks. looks good !! Co-authored-by: Jack Baldry --- docs/sources/sample-dashboards/_index.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/sources/sample-dashboards/_index.md b/docs/sources/sample-dashboards/_index.md index 588805f7..d7f14700 100644 --- a/docs/sources/sample-dashboards/_index.md +++ b/docs/sources/sample-dashboards/_index.md @@ -1,7 +1,7 @@ --- -title: Create a sample dashboards for the Grafana GitHub data source plugin -menuTitle: Sample dashboards -description: Learn how to import pre-made example dashboards +title: Create sample dashboards for the Grafana GitHub data source plugin for Grafana +menuTitle: Create sample dashboards +description: Learn how to import example dashboards into Grafana for use with the GitHub data source plugin for Grafana keywords: - data source - github @@ -15,29 +15,30 @@ labels: weight: 500 --- -# Create a sample dashboards the GitHub data source plugin using Grafana +# Create sample dashboards for the GitHub data source plugin for Grafana This page explains how you can create a sample dashboard in Grafana to get started with the GitHub data source plugin. You can obtain these sample dashboards by: - Using pre-configured dashboards - Using play demo -## Using pre-configure dashboards +## Use pre-configured dashboards The pre-configured dashboards are ready-to-use and you only need to import them inside your Grafana server. There are two ways to use the pre-configure dashboards: - Importing from the official Website - Importing from the Grafana server WebUI -### Importing from the official Website +### Import from the Dashboards page on grafana.com -Import the dashboards from the official page [located here](https://grafana.com/grafana/dashboards/14000). +Import the [GitHub Default dashboard](https://grafana.com/grafana/dashboards/14000). -For instructions on how to import dashboards in Grafana, see [Import a dashboard](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard) and replace the ID with `1400`. +For instructions on how to import dashboards in Grafana, refer to [Import a dashboard](https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard). +The dashboard ID is `1400`. -### Importing from the Grafana server WebUI +### Import in the Grafana UI -To view a list of pre-made GitHub dashboards do the following: +To import a dashboard in the Grafana UI: 1. Go to **Connections** in the sidebar menu. 1. Under Connections, click **Data sources**. @@ -47,6 +48,6 @@ To view a list of pre-made GitHub dashboards do the following: ## Play demo -The Play demo dashboards prvoide a reference, allows you to create your own custom dashboards. +The Play demo dashboards provides a reference dashboard and allows you to create your own custom dashboards. {{< docs/play title="GitHub data source plugin demo" url="https://play.grafana.org/dashboards/f/bb613d16-7ee5-4cf4-89ac-60dd9405fdd7/demo-github" >}}