Set up instantaneous pulling and dashboard previews in Pull Requests

After setup, you can optionally extend Git Sync by enabling pull request notifications and image previews of dashboard changes.

Set up webhooks for real-time notification and pull request integration

Real-time notifications (or automatic pulling) is enabled and configured by default in Grafana Cloud.

In Grafana OSS/Enterprise, Git Sync uses webhooks to enable real-time updates from GitHub public repositories, or to enable pull request integrations. Without webhooks the polling interval is set during configuration, and is 60 seconds by default. You can set up webhooks with whichever service or tooling you prefer: Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as ngrok.

To set up webhooks:

1. Expose your Grafana instance to the public Internet.
   • Use port forwarding and DNS, ngrok, or any other method you prefer.
   • The permissions set in your GitHub access token provide the authorization for this communication.
2. After you have the public URL, add it to your Grafana configuration file:
   iniCopy

   [server]
   root_url = https://<PUBLIC_DOMAIN>
   

3. Replace <PUBLIC_DOMAIN> with your public domain.

To check the configured webhooks, go to Administration > General > Provisioning and click the View link for your GitHub repository.

Webhook limits

Git Sync registers its own webhooks for each repository connection, so when several Grafana instances sync the same repository, each connection adds to this total. Since Git providers limit the amount of webhooks you can set for each repository, when the limit is exceeded, your Git provider rejects new webhooks.

For example, in GitHub you can get an error such as:

GitHub API error (HTTP 422: Validation Failed: The "pull_request" event cannot have more than 20 hooks; The "push" event cannot have more than 20 hooks)

If you hit this limit, you can either:

• Remove unused or duplicate webhooks from your repository's Settings > Webhooks page.
• Disable webhook integration for connections that don't need real-time sync so those instances poll on an interval instead. Refer to Webhook options to disable webhook integration.

Webhook limitations per provider

The following limits apply:

• GitHub limits each repository to 20 webhooks per event type, such push and pull_request. For more information refer to the official GitHub webhooks documentation.
• GitLab defaults to 100 webhooks for each project, 50 for each group, although subgroup webhooks are not counted towards parent group limits. Refer to GitLab settings for more information.
• BitBucket limits to 50 webhooks per repository. Refer to BitBucket webhook documentation for more details.

Set a publicly-reachable URL

If you need to point [server] root_url to an internal address (for example, when Grafana runs behind a private ingress in a Kubernetes cluster), set the publicly-reachable URL with [provisioning] public_root_url instead. This URL is used both to register webhook callbacks with the Git provider and as the base for screenshot images embedded in pull-request comments, which the Git provider's servers fetch from the public internet.

[server]
root_url = http://internal.cluster.local

[provisioning]
public_root_url = https://<PUBLIC_DOMAIN>

The per-repository spec.webhook.baseUrl field still overrides public_root_url for webhook registration, and screenshot URLs always use public_root_url (or root_url when unset).

Expose necessary paths only

If your security setup doesn't permit publicly exposing the Grafana instance, you can either choose to allowlist the Git provider's IP addresses, or expose only the necessary paths.

For information about the traffic between Grafana and your Git server, refer to Network connectivity and IP allowlisting.

In RegExp, the necessary paths required to be exposed are /apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$.

Set up image rendering for dashboard previews

{{< admonition type="caution" >}}

Available in Grafana OSS and Grafana Enterprise only.

{{< /admonition >}}

To set up image rendering to add visual previews of dashboard updates directly in pull requests, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the Image Renderer service.

Image rendering requires webhooks.

Next steps

To learn more about using Git Sync refer to the following documents:

• Set up Git Sync
• Export resources
• Work with provisioned repositories
• Work with provisioned dashboards
• Git Sync deployment scenarios