Docs: Updated GitHub data source docs by lwandz13 · Pull Request #676 · grafana/github-datasource

lwandz13 · 2026-03-11T21:33:42Z

Overhaul the GitHub data source plugin documentation to align with Grafana's official documentation standards. This restructures fragmented pages into a flat file layout, adds missing content, verifies accuracy against the codebase, and improves overall clarity and flow.

Structure changes

Consolidated 12 files across 5 directories into 7 flat files under docs/sources/:

setup/* (5 files) → configure.md
query/_index.md → query-editor.md
variables-and-macros/* (3 files) → template-variables.md
annotations/_index.md → annotations.md
troubleshoot/_index.md → troubleshooting.md
sample-dashboards/_index.md content merged into _index.md

Created new alerting.md — The plugin supports alerting (plugin.json: "alerting": true) but had no documentation for it.

Content additions

_index.md: Added Requirements, Common use cases (7 engineering scenarios), expanded Pre-built dashboards section with panel descriptions.
configure.md: Added Security best practices section, Terraform provisioning examples (PAT, GitHub App, Enterprise Server), PDC "Manage" link, improved Save & test guidance. Elevated Code scanning permissions to apply to both PATs and GitHub Apps.
query-editor.md: Added documentation for Code scanning and Pull request reviews query types. Added 7 new sample queries across Issues, Pull Requests, Pull Request Reviews, and Workflow Runs. Fixed response field inaccuracies verified against Go source (star_count typo, missing author_email, state, milestone, is_fork, merged_by_email, merged_by_company, updated_at, open_time, labels).
alerting.md: New page covering supported query types, step-by-step alert rule creation, 3 example alert configurations, caching considerations, and template annotations/labels.
annotations.md: Added 3 use case examples (releases on performance dashboards, deployment tracking, merged PRs alongside commits).
template-variables.md: Added Before you begin, Supported variable types, multi-variable dashboard walkthrough (owner → repo → labels chaining), improved macro descriptions (prefix → qualifier terminology).
troubleshooting.md: Expanded from a brief page to comprehensive coverage: auth errors (PAT, GitHub App, private repos), connection errors (Enterprise Server, network), query errors (no data, result limits with source attribution, rate limiting), code scanning errors, debug logging, and escalation guidance.

cla-assistant · 2026-03-11T21:33:56Z

All committers have signed the CLA.

Resolve modify/delete conflict on docs/sources/query/_index.md by keeping the deletion (content lives in query-editor.md) and incorporating the new Commit files, Pull request files, and Include files (Commits) documentation from #654 into query-editor.md. Made-with: Cursor

Copilot

Pull request overview

Overhauls and consolidates the GitHub data source plugin documentation into a flatter, Grafana-standard page structure under docs/sources/, adding missing feature coverage (notably alerting) and expanding guidance for configuration, querying, variables, and troubleshooting.

Changes:

Consolidates prior multi-directory docs into a smaller set of top-level docs pages with aliases for old routes.
Adds/expands documentation for query editor behavior, template variables/macros, alerting, annotations, and troubleshooting.
Updates the docs landing page content (requirements, capabilities, use cases, dashboards, caching, and resources).

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
docs/sources/_index.md	Updates landing page content, adds aliases, requirements, capabilities, use cases, dashboards, caching.
docs/sources/configure.md	New consolidated configuration/auth/provisioning (YAML + Terraform) guide.
docs/sources/query-editor.md	New consolidated query editor reference across query types and response fields.
docs/sources/template-variables.md	New consolidated template variables + macros documentation with walkthrough examples.
docs/sources/annotations.md	New consolidated annotations guide with use-case examples.
docs/sources/alerting.md	New alerting page describing supported patterns and examples.
docs/sources/troubleshooting.md	New expanded troubleshooting guide for auth/connection/query/code scanning/debugging.
docs/sources/query/_index.md	Removes old query docs (replaced by `query-editor.md` + alias).
docs/sources/setup/_index.md	Removes old setup index (replaced by `configure.md` + alias).
docs/sources/setup/installation.md	Removes old installation page (covered by `configure.md`).
docs/sources/setup/token.md	Removes old token page (covered by `configure.md`).
docs/sources/setup/datasource.md	Removes old datasource config page (covered by `configure.md`).
docs/sources/setup/provisioning.md	Removes old provisioning page (covered by `configure.md`).
docs/sources/variables-and-macros/_index.md	Removes old variables/macros index (replaced by `template-variables.md` + aliases).
docs/sources/variables-and-macros/variables.md	Removes old variables page (replaced by `template-variables.md`).
docs/sources/variables-and-macros/macros.md	Removes old macros page (replaced by `template-variables.md`).
docs/sources/annotations/_index.md	Removes old annotations page (replaced by `annotations.md` + alias).
docs/sources/troubleshoot/_index.md	Removes old troubleshooting page (replaced by `troubleshooting.md` + alias).
docs/sources/sample-dashboards/_index.md	Removes old sample dashboards page (content merged; alias added on landing page).
.vscode/settings.json	Adds a VS Code workspace setting.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- Add missing run_started_at field to Workflow Runs response docs - Update "19 resource types" to "20+" to reflect new query types - Add .vscode/ to .gitignore Made-with: Cursor

Terraform's jsonencode function is used in the provisioning examples in configure.md. Made-with: Cursor

fabrizio-grafana

Overall looks really good to me, I just left I couple of comments on things we might want to double check, to ensure the documentation is up-to-date with the codebase.

lwandz13 · 2026-04-28T14:49:50Z

@fabrizio-grafana, thanks for your review! I've made the requested changes, and this is ready for a re-review.

fabrizio-grafana

Thank you!

lwandz13 added 10 commits March 11, 2026 11:09

restructured the content

b50bea5

updated _index

8cb23dc

updates configure docs

540aee5

updates to query editor

a16a10e

restructured template variables

8689477

troubleshooting updates

f0513f3

added an alerting doc

993a5c8

added some use cases

ee88967

additional updates to config and main page

f0c4f7b

final edits

ca2c803

lwandz13 requested review from a team, irenerl24 and k-munoz March 11, 2026 21:33

lwandz13 self-assigned this Mar 11, 2026

lwandz13 added the type/docs Improvements or additions to documentation label Mar 11, 2026

grafana-oss-big-tent Bot added this to OSS Big Tent Mar 11, 2026

github-project-automation Bot moved this to Backlog in OSS Big Tent Mar 11, 2026

Merge branch 'main' into docs/update-github-docs

1419be0

lwandz13 moved this from Backlog to Awaiting Review in OSS Big Tent Apr 7, 2026

lwandz13 added 2 commits April 20, 2026 16:33

resolved merge conflicts and cleaned up some language

8be1f8b

Copilot AI review requested due to automatic review settings April 20, 2026 21:34

lwandz13 requested a review from a team as a code owner April 20, 2026 21:34

Copilot started reviewing on behalf of lwandz13 April 20, 2026 21:34 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

katebrenner assigned fabrizio-grafana Apr 21, 2026

lwandz13 and others added 3 commits April 21, 2026 10:22

Update docs/sources/query-editor.md

bb82ce1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/sources/query-editor.md

439e86f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/sources/query-editor.md

170d8d4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

lwandz13 and others added 6 commits April 21, 2026 10:23

Update docs/sources/_index.md

6faac03

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/sources/_index.md

7ff146e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Address review feedback from merge

2c6ec02

- Add missing run_started_at field to Workflow Runs response docs - Update "19 resource types" to "20+" to reflect new query types - Add .vscode/ to .gitignore Made-with: Cursor

Merge branch 'main' into docs/update-github-docs

47cd2a2

Merge branch 'main' into docs/update-github-docs

443b299

Add jsonencode to cspell dictionary

5addf10

Terraform's jsonencode function is used in the provisioning examples in configure.md. Made-with: Cursor

fabrizio-grafana reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/sources/query-editor.md Outdated

Comment thread docs/sources/query-editor.md

updates based on dev feedback

be2f62a

lwandz13 mentioned this pull request Apr 28, 2026

[EPIC] Add a troubleshooting guide to Grafana data sources grafana/grafana#123741

Open

62 tasks

fabrizio-grafana approved these changes Apr 29, 2026

View reviewed changes

lwandz13 merged commit 33f3b07 into main Apr 29, 2026
26 of 29 checks passed

github-project-automation Bot moved this from Awaiting Review to Complete in OSS Big Tent Apr 29, 2026

lwandz13 deleted the docs/update-github-docs branch April 29, 2026 13:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Updated GitHub data source docs#676

Docs: Updated GitHub data source docs#676
lwandz13 merged 23 commits intomainfrom
docs/update-github-docs

lwandz13 commented Mar 11, 2026

Uh oh!

cla-assistant Bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabrizio-grafana left a comment

Uh oh!

Uh oh!

Uh oh!

lwandz13 commented Apr 28, 2026

Uh oh!

fabrizio-grafana left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

lwandz13 commented Mar 11, 2026

Uh oh!

cla-assistant Bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabrizio-grafana left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lwandz13 commented Apr 28, 2026

Uh oh!

fabrizio-grafana left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cla-assistant Bot commented Mar 11, 2026 •

edited

Loading