Set up Git Sync on Grafana Labs

Setup prerequisites

Wed, 28 Oct 2026 09:22:36 +0000

Before you begin

Before you begin to set up Git Sync, ensure you have the following:

A Grafana instance (Cloud, OSS, or Enterprise)
Administration rights in your Grafana organization
A Git provider
If you’re using webhooks or image rendering, a public instance with external access
Optional: The Image Renderer service to save image previews with your PRs

Enable required feature toggles

The provisioning feature toggle is enabled by default in Grafana Cloud and, starting in Grafana v13, for OSS and Enterprise as well. No manual configuration is required.

For more information about feature toggles, refer to Configure feature toggles.

Enable Git providers

If you’re using Grafana Enterprise v12.4.0 and want to set up Git Sync with pure Git, GitLab or Bitbucket, or if you’re using Grafana OSS v12.4.0 and want to set up Git Sync with pure Git, add them to your configuration file:

Open your Grafana configuration file, either grafana.ini or custom.ini.

Add the available providers:

[provisioning]
repository_types = "git|github|bitbucket|gitlab|local"

Save the changes to the file and restart Grafana.

Enable OAuth connection types

If you’re using self-managed Grafana and the OAuth App connection type for your provider isn’t available, add it to connection_types in your configuration file:

Open your Grafana configuration file, either grafana.ini or custom.ini.

Add the connection types:

[provisioning]
connection_types = "github|githubOAuth|gitOAuth"

Save the changes to the file and restart Grafana.

The available OAuth connection types are:

Connection type	Provider	Available in
`githubOAuth`	GitHub	OSS, Enterprise
`gitOAuth`	Pure Git	OSS, Enterprise
`githubEnterpriseOAuth`	GitHub Enterprise	Enterprise
`gitlabOAuth`	GitLab	Enterprise
`bitbucketOAuth`	Bitbucket	Enterprise

Network connectivity and IP allowlisting

Git Sync requires network connectivity between your Grafana instance and Git server. Understanding the traffic patterns helps you configure firewall rules and allowlists correctly.

Traffic types

Git Sync uses two types of network traffic:

Sync operations (pull and push): From Grafana to the Git Server
- Egress traffic from Hosted Grafana IP addresses
- Your Git servers must allow inbound traffic from these IP addresses
- For a list of IP addresses to add to your Git server’s allowlist, refer to Hosted Grafana source IPs
Webhooks (instantaneous sync): From the Git Server to Grafana stack
- Inbound traffic to the stack’s public endpoint
- Your Git server must be able to reach *.grafana.net
- Required only if you’re using webhooks

AWS PrivateLink and Private Data Source Connect

Git Sync doesn’t route over AWS PrivateLink or Private Data Source Connect (PDC). Instead, Git Sync uses the normal public path from the Hosted Grafana IPs, which is independent from PrivateLink and PDC. AWS PrivateLink and PDC provide a separate tunnel for data source query traffic, from Grafana to your private databases or data sources.

If you use AWS PrivateLink or PDC for data sources, you can still use Git Sync. The two features neither interfere with nor depend on each other.

Allow internal or private Git servers

Note
This setting is available for Grafana v13.0.4 and Grafana v13.1.1 and later. It only applies to self-managed Grafana (OSS and Enterprise), but it’s not configurable in Grafana Cloud.

While public Git servers such as github.com, gitlab.com, and bitbucket.org resolve to public addresses and are always allowed, by default Git Sync rejects repository URLs with a host that resolves to a loopback, a private (RFC 1918), link-local, or an unspecified address. This protects your Grafana instance against server-side request forgery (SSRF).

If you connect Git Sync to a Git server on a private network such as a self-hosted GitHub Enterprise, GitLab, or Bitbucket instance reachable only through an internal address, add its host to the allowed_git_urls allowlist:

Open your Grafana configuration file, either grafana.ini or custom.ini.

Add each internal Git host to allowed_git_urls as a comma-separated list:

[provisioning]
allowed_git_urls = git.internal.example.com, ghe.example.com:8443

Save the changes to the file and restart Grafana.

Each entry can be a hostname, host:port, a full URL (only the host is used), a literal IP address, or a CIDR range. If possible, use specific hosts or narrow ranges, since a broad CIDR such as 10.0.0.0/8 re-exposes the entire private range that SSRF protection blocks.

Only add hosts you trust because an allowlisted host receives the configured Git token on every sync, fetch, and push.

Resource and role permissions

By default, folders provisioned with Git Sync have these roles:

Admin = Admin
Editor = Editor
Viewer = Viewer.

Refer to Git Sync permissions for details on how to set up permissions in Git Sync. To modify them, refer to Manage folder permissions.

Refer to Roles and permissions for more information about Grafana roles.

Create a GitHub App

GitHub Apps are tools that extend GitHub functionality. They use fine-grained permissions and short-lived tokens, giving you more control over which repositories are being accessed. Find out more in the GitHub Apps official documentation.

If you chose to authenticate with a newly created GitHub App, you’ll need the following parameters:

GitHub App ID
GitHub App Private Key
GitHub App Installation ID

There are many ways to create a GitHub App. The following instructions are informative only, always refer to official GitHub documentation for more details.

To create the GitHub App, follow these steps:

Go to https://github.com/settings/apps and click on New Github App, or navigate directly to https://github.com/settings/apps/new
Fill in the following fields:
- Name: Must be unique
- Homepage URL: For example, your Grafana Cloud instance URL
Scroll down to the Webhook section and uncheck the Active box
In the Permissions section, go to Repository permissions and set these parameters:
- Administration: Read-only permission (enables validation of branch protection rules against the configured branch when users can push directly to it; may be used in the future to check other repository settings and make the setup process smoother)
- Contents: Read and write permission
- Metadata: Read-only permission
- Pull requests: Read and write permission
- Webhooks: Read and write permission
Finally, under Where can this GitHub App be installed?, select Only on this account
Click on Create Github App to complete the process.

On the app page:

Copy the AppID from the About section
Select the Generate private key from the banner or scroll down to to the Private Keys section to generate a key
A PEM file containing your private key will be downloaded to your computer

Finally, install the app:

At the top left of the App page, click on Install App
Choose for which user you need to install it, you’ll be redirected to the repository selection screen
Choose for which repositories you want to install the app
Click Install.
On the installation page, copy installationID from the page URL https://github.com/settings/installations/installationID

You can now proceed to Set up Git Sync!

Create an OAuth App

An OAuth App lets Grafana act on your behalf in your Git provider. You create the app in your provider, then authorize it once from Grafana. Grafana stores the access token and refreshes it when the provider supports refresh tokens.

Caution
An OAuth App connection acts as the user who authorized it. Every repository that uses the connection and every user who can run its sync jobs will use the access token of the user that authorized the connection. The token can reach every repository that user can access, not only those connected to Grafana. Removing the user from Grafana doesn’t revoke the token. Revoke it in your Git provider.

To limit access, authorize the app with a dedicated account that can only access the repositories you sync. For GitHub, consider a GitHub App, which is scoped to the repositories where it’s installed.

If you chose to authenticate with an OAuth App, you need the following parameters:

The client ID of the app.
The client secret of the app.

Every OAuth App needs the Grafana callback URL. Grafana shows it in the setup wizard, and it has this format:

<GRAFANA_URL>/admin/provisioning/connections/oauth-callback

Replace <GRAFANA_URL> with the root URL of your Grafana instance, including any sub-path.

The following instructions are informative only. Always refer to the official documentation of your Git provider for more details.

GitHub and GitHub Enterprise

To create a GitHub OAuth App, follow these steps:

In GitHub, go to Settings > Developer settings > OAuth apps and click New OAuth App. For GitHub Enterprise, use the same menu on your enterprise instance.
Enter an Application name and a Homepage URL, for example your Grafana instance URL.
Paste the Grafana callback URL in Authorization callback URL.
Click Register application.
Copy the Client ID, then click Generate a new client secret and copy the secret.

Grafana requests the repo scope when you authorize the app. For more details, refer to Creating an OAuth app.

GitLab

To create a GitLab OAuth application, follow these steps:

In GitLab, create the application for your user or for a group:
- For your user, select your avatar, then Edit profile > Access > Applications > Add new application.
- For a group, go to the group and select Settings > Applications.
Enter a Name and paste the Grafana callback URL in Redirect URI.
Keep Confidential selected, and select the api scope.
Click Save application.
Copy the Application ID and the Secret.

For more details, refer to Configure GitLab as an OAuth 2.0 authentication identity provider.

Bitbucket

To create a Bitbucket OAuth consumer, follow these steps:

In Bitbucket, go to Workspace settings > Apps and features > OAuth consumers and click Add consumer.
Enter a Name and paste the Grafana callback URL in Callback URL.
Set these permissions:
- Repositories: Read and write permission
- Pull requests: Read and write permission
- Webhooks: Read and write permission
Click Save.
Select the consumer name to show the Key and the Secret, copy them, and note the name of the workspace.

For more details, refer to Use OAuth on Bitbucket Cloud.

Other Git providers

For any other Git provider that supports the OAuth 2.0 authorization code flow, create an OAuth application with the Grafana callback URL as the redirect URI. In addition to the client ID and secret, you need:

The Authorization URL of the provider, for example https://git.example.com/oauth/authorize.
The Token URL of the provider, for example https://git.example.com/oauth/token.
The Scopes that grant read and write access to your repositories. Refer to your provider’s documentation.

Both URLs must use https://, unless you set allow_insecure in the [provisioning] section of your configuration file.

Next steps

For further details on how Git Sync operates, refer to:

Set up Git Sync as code

Tue, 03 Nov 2026 16:35:21 +0000

Set up Git Sync as code

You can also configure Git Sync using gcx, the Grafana CLI. Since Git Sync configuration is managed as code using Custom Resource Definitions (CRDs), you can create your required resources in YAML files and push them to Grafana using gcx. This approach enables automated, GitOps-style workflows for managing Git Sync configuration instead of using the Grafana UI.

For more information, refer to the following documents:

Repository resource and Connection resource overview
Dashboard CRD Format
Grafana CLI documentation

To provision resources from a local file system as code instead of a Git repository, refer to Set up file provisioning as code.

Set up Git Sync as code with the Grafana CLI

To set up Git Sync as code with gcx, follow these steps:

Before you begin

Understand the following:

Git Sync Usage and performance limitations.
The required resources (connection and repository) to use Git Sync.

Create the connection resource

A connection is the authentication setup between Grafana and an external Git provider, required when you’re not using a Personal Access Token or a static token to authenticate.

Create a GitHub App connection resource

If you’re connecting Git Sync with GitHub App, create a connection.yaml file defining your Git Sync connection configuration:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Connection
metadata:
  name: '<GITHUB_CONNECTION_NAME>'
  namespace: default
spec:
  title: '<REPOSITORY_TITLE>'
  type: github
  url: https://github.com
  github:
    appID: '<GITHUB_APP_ID>'
    installationID: '<GITHUB_INSTALL_ID>'
secure:
  privateKey:
    create: '<GITHUB_PRIVATE_KEY>'

If your GitHub App is installed on GitHub Enterprise Server, set the type to githubEnterprise and use the githubEnterprise block instead:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Connection
metadata:
  name: '<GITHUB_CONNECTION_NAME>'
  namespace: default
spec:
  title: '<REPOSITORY_TITLE>'
  type: githubEnterprise
  githubEnterprise:
    appID: '<GITHUB_APP_ID>'
    installationID: '<GITHUB_INSTALL_ID>'
    serverUrl: '<GITHUB_ENTERPRISE_SERVER_URL>'
secure:
  privateKey:
    create: '<GITHUB_PRIVATE_KEY>'

Replace the placeholders with your values:

<GITHUB_CONNECTION_NAME>: The name of your GitHub connection
<REPOSITORY_TITLE>: Human-readable name displayed in Grafana UI
<GITHUB_APP_ID>: GitHub App unique identifier
<GITHUB_INSTALL_ID>: GitHub App installation id
<GITHUB_PRIVATE_KEY>: GitHub App private key, base64-encoded
<GITHUB_ENTERPRISE_SERVER_URL>: The URL of your GitHub Enterprise Server instance, for example https://ghes.example.com

Create an OAuth App connection resource

If you’re connecting Git Sync with an OAuth App, create a connection.yaml file with the client ID and secret of the app, and the fields for your provider:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Connection
metadata:
  name: '<OAUTH_CONNECTION_NAME>'
  namespace: default
spec:
  title: '<CONNECTION_TITLE>'
  type: '<CONNECTION_TYPE>' # githubOAuth, githubEnterpriseOAuth, gitlabOAuth, bitbucketOAuth, or gitOAuth
  oauth:
    clientID: '<CLIENT_ID>'
  # GitHub Enterprise only:
  githubEnterpriseOAuth:
    serverUrl: '<GITHUB_ENTERPRISE_SERVER_URL>'
  # Bitbucket only:
  bitbucket:
    workspace: '<BITBUCKET_WORKSPACE>'
  # Pure Git only:
  gitOAuth:
    authURL: '<AUTHORIZATION_URL>'
    tokenURL: '<TOKEN_URL>'
    scopes:
      - '<SCOPE>'
secure:
  clientSecret:
    create: '<CLIENT_SECRET>'

Replace the placeholders with your values:

<OAUTH_CONNECTION_NAME>: The name of your OAuth App connection
<CONNECTION_TITLE>: Human-readable name displayed in Grafana UI
<CONNECTION_TYPE>: The OAuth connection type for your provider
<CLIENT_ID>: The client ID of the OAuth App
<CLIENT_SECRET>: The client secret of the OAuth App
<GITHUB_ENTERPRISE_SERVER_URL>: The URL of your GitHub Enterprise instance
<BITBUCKET_WORKSPACE>: The workspace that the OAuth consumer belongs to
<AUTHORIZATION_URL>, <TOKEN_URL>, <SCOPE>: The OAuth endpoints of your Git provider, and the scopes that grant read and write access to your repositories

An OAuth App connection needs a user to approve access in the browser. After you push the connection, it shows as Disconnected until you authorize it:

Select Administration > General > Provisioning and go to the Connections tab.
Select the connection and click Reauthorize.
Approve the access in the provider tab that opens.

Create the repository resource

A repository resource is a Grafana configuration object that defines the connection between a group of repositories and your Grafana instance via Git Sync. Depending on your Git provider and authentication method, add your Personal Access Token information or the connection name.

Create a repository.yaml file defining your Git Sync configuration:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: '<REPOSITORY_NAME>'
spec:
  sync:
    enabled: true
    intervalSeconds: 60
    target: '<YOUR_TARGET'>
  workflows:
    - write
    - branch
  title: '<REPOSITORY_TITLE>'

# Git Sync for GitHub:
spec:
  type: github
  github:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: grafana/
  # GitHub App or OAuth App connection only:
  connection:
    name: '<GITHUB_CONNECTION_NAME>'
# GitHub Personal Access Token only:
secure:
  token: { create: 'GIT_PAT' }

# Git Sync for GitHub Enterprise:
spec:
  type: githubEnterprise
  githubEnterprise:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: grafana/
  # GitHub Enterprise App connection only:
  connection:
    name: '<GITHUB_ENTERPRISE_CONNECTION_NAME>'
# GitHub Personal Access Token only:
secure:
  token: { create: 'GIT_PAT' }

# GitLab Personal Access Token only:
spec:
  type: gitlab
  gitlab:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
secure:
  token: { create: 'GIT_PAT' }

# Bitbucket Personal Access Token only:
spec:
  type: bitbucket
  bitbucket:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    tokenUser: tokenuser
secure:
  token: { create: 'GIT_PAT' }

# Pure Git only:
spec:
  type: git
  git:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: 'grafana/'
    tokenUser: tokenuser
secure:
  token: { create: 'GIT_PAT' }

To use an OAuth App connection, set spec.connection.name instead of secure.token. The repository type must match the connection type: githubOAuth for github, githubEnterpriseOAuth for githubEnterprise, gitlabOAuth for gitlab, bitbucketOAuth for bitbucket, and gitOAuth for git.

Replace the placeholders with your values:

<YOUR_TARGET>: Git Sync supports two sync targets: folder (default) creates a folder named after the repository and places synced resources inside it, while folderless places synced resources at the top level without creating a wrapper folder. Refer to Sync targets for details.
<REPOSITORY_NAME>: Unique identifier for this repository resource.
<REPOSITORY_TITLE>: Human-readable name displayed in Grafana UI.
<GIT_REPO_URL>: GitHub repository URL.
<BRANCH>: Branch to sync.
<GITHUB_CONNECTION_NAME>: The name of your GitHub connection.
<GITHUB_ENTERPRISE_CONNECTION_NAME>: The name of your GitHub Enterprise connection.
<GIT_PAT>: Git provider Personal Access Token.

Configuration parameters

The following configuration parameters are available for the connection and repository resources.

Values under secure are stored encrypted and can’t be read back after you create them.

Connection parameters

Field	Description
`metadata.name`	Unique identifier for this connection resource. Repositories reference the connection by this name
`spec.title`	Human-readable name displayed in Grafana UI
`spec.description`	Description of the connection
`spec.type`	Connection type: `github`, `githubEnterprise`, `githubOAuth`, `githubEnterpriseOAuth`, `gitlabOAuth`, `bitbucketOAuth`, or `gitOAuth`
`spec.url`	URL of the Git provider, for example `https://github.com`
`spec.github.appID`	GitHub App ID. Only for the `github` type
`spec.github.installationID`	GitHub App installation ID. Only for the `github` type
`spec.githubEnterprise.appID`	GitHub App ID. Only for the `githubEnterprise` type
`spec.githubEnterprise.installationID`	GitHub App installation ID. Only for the `githubEnterprise` type
`spec.githubEnterprise.serverUrl`	URL of your GitHub Enterprise Server instance, for example `https://ghes.example.com`. Only for the `githubEnterprise` type
`spec.oauth.clientID`	Client ID of the OAuth App. Required for all OAuth connection types
`spec.githubEnterpriseOAuth.serverUrl`	URL of your GitHub Enterprise Server instance. Only for the `githubEnterpriseOAuth` type
`spec.bitbucket.workspace`	Workspace that the OAuth consumer belongs to. Only for the `bitbucketOAuth` type
`spec.gitOAuth.authURL`	OAuth authorization endpoint of your Git provider, for example `https://gitlab.example.com/oauth/authorize`. Only for the `gitOAuth` type
`spec.gitOAuth.tokenURL`	OAuth token endpoint of your Git provider, for example `https://gitlab.example.com/oauth/token`. Only for the `gitOAuth` type
`spec.gitOAuth.scopes`	OAuth scopes to request. The scopes must grant read and write access to your repositories. Only for the `gitOAuth` type
`spec.webhook.disabled`	Disable webhooks for this connection (true/false). When `true`, the GitHub App doesn’t need the `webhooks:write` permission, and Grafana doesn’t register or receive webhook events. Use it if Grafana isn’t reachable from the public internet
`secure.privateKey.create`	Private key of the GitHub App, base64-encoded. Only for the `github` and `githubEnterprise` types
`secure.clientSecret.create`	Client secret of the OAuth App. Required for all OAuth connection types

Repository parameters

In the following table, replace <TYPE> with the repository type set in spec.type. For example, use spec.gitlab.url for a GitLab repository.

Field	Description
`metadata.name`	Unique identifier for this repository resource
`spec.title`	Human-readable name displayed in Grafana UI
`spec.description`	Description of the repository
`spec.type`	Repository type: `github`, `githubEnterprise`, `gitlab`, `bitbucket`, or `git`
`spec.<TYPE>.url`	Repository URL, for example `https://github.com/example/test`
`spec.<TYPE>.branch`	Branch to sync
`spec.<TYPE>.path`	Directory path in the repository that contains your Grafana resources, for example `grafana/`. Grafana ignores anything outside this path
`spec.githubEnterprise.serverUrl`	URL of your GitHub Enterprise Server instance, for example `https://ghes.example.com`
`spec.bitbucket.tokenUser`	User that owns the Personal Access Token
`spec.bitbucket.email`	Atlassian account email used to authenticate with the Bitbucket REST API. Required to enable webhooks
`spec.git.tokenUser`	User that owns the Personal Access Token
`spec.github.generateDashboardPreviews`	Generate dashboard preview images in pull requests (true/false). Only for the `github` type. For other types, use `spec.pullRequest.generateDashboardPreviews`
`spec.connection.name`	Name of the connection resource used to authenticate. Use it instead of `secure.token` when you connect with a GitHub App or an OAuth App
`spec.sync.enabled`	Enable synchronization (true/false)
`spec.sync.intervalSeconds`	Sync interval in seconds. If the value is lower than the system minimum, Grafana uses the system minimum instead
`spec.sync.target`	Where to place synced resources (`folder` or `folderless`)
`spec.workflows`	Enabled workflows: `write` (direct commits), `branch` (PRs). The order defines which workflow takes precedence. If empty, the repository is read-only
`spec.commit.singleResourceMessageTemplate`	Template for the commit messages of single-resource operations in the Grafana UI, such as saving, moving, or deleting a dashboard. Supports `{{action}}`, `{{resourceKind}}`, `{{resourceID}}`, `{{title}}`, `{{userName}}`, `{{userLogin}}`, and `{{userEmail}}`. If empty, Grafana uses a default message, for example `Save dashboard: <TITLE>`
`spec.commit.enforceTemplate`	Pre-fill the comment field in the save drawer from the commit message template and make it read-only (true/false)
`spec.commit.authorName`	Name used as the commit author instead of the user who made the change. Only valid if `spec.commit.signingMethod` isn’t set
`spec.commit.authorEmail`	Email used as the commit author instead of the user who made the change. Only valid if `spec.commit.signingMethod` isn’t set
`spec.commit.signingMethod`	Method used to sign commits with the key in `secure.commitSigningKey`: `gpg`, `ssh`, or `smime`. If empty, commits aren’t signed
`spec.commit.signerName`	Name of the commit signer. Must match the identity of the signing key for your Git provider to mark commits as verified. Defaults to `Grafana`
`spec.commit.signerEmail`	Email of the commit signer. Must match the identity of the signing key, and a verified email on the account where the matching public key is registered. Defaults to `noreply@grafana.com`
`spec.commit.signerIsAuthor`	Use the signer identity (`signerName` and `signerEmail`) as the commit author (true/false)
`spec.commit.smimeCertificate`	PEM-encoded X.509 certificate paired with the signing key. Only used if `spec.commit.signingMethod` is `smime`
`spec.branch.nameTemplate`	Template for the names of branches created by the `branch` workflow. Supports `{{action}}`, `{{resourceKind}}`, `{{title}}`, `{{userLogin}}`, and `{{random}}`, a random 6-character string. Grafana converts the result to a valid branch name of up to 100 characters
`spec.branch.enforceTemplate`	Make the branch name field in the save drawer read-only (true/false)
`spec.pullRequest.titleTemplate`	Template for pull request titles. Supports the same variables as `spec.branch.nameTemplate`. If empty, Grafana uses the first line of the commit message
`spec.pullRequest.enforceTemplate`	Make the pull request title field in the save drawer read-only (true/false)
`spec.pullRequest.generateDashboardPreviews`	Generate dashboard preview images in pull requests (true/false). For all types except `github`
`spec.webhook.baseUrl`	Base URL of your Grafana instance used to register webhooks with your Git provider, for example `https://grafana.example.com`. Overrides the auto-detected public URL of Grafana
`spec.webhook.disabled`	Disable webhooks for this repository (true/false). When `true`, Grafana polls the repository at the sync interval instead. Use it if Grafana isn’t reachable from the public internet
`secure.token.create`	Personal Access Token of your Git provider. Not needed if you use `spec.connection.name`
`secure.commitSigningKey.create`	Private key used to sign the commits Grafana writes to the repository. The format depends on `spec.commit.signingMethod`

Push the resources to Grafana

Before pushing any resources, configure gcx with your Grafana instance details. Refer to the Grafana CLI documentation for setup instructions.

Next, push the connection (if required) and repository configuration files:

gcx resources push --path <DIRECTORY>

The --path parameter has to point to the directory containing your repository.yaml and connection.yaml files.

After pushing, Grafana will:

Create the required resources (repository and, for GitHub App or OAuth, connection).
Connect to your GitHub repository.
Pull dashboards from the specified path.
Begin syncing at the configured interval.

Manage repository resources

List repositories

To list all repositories:

gcx resources get repositories

Get repository details

To get details for a specific repository:

gcx resources get repository/<REPOSITORY_NAME>
gcx resources get repository/<REPOSITORY_NAME> -o json
gcx resources get repository/<REPOSITORY_NAME> -o yaml

Update the repository

To update a repository:

gcx resources edit repository/<REPOSITORY_NAME>

Delete the repository

To delete a repository:

gcx resources delete repository/<REPOSITORY_NAME>

Verify setup

Check that Git Sync is working:

# List repositories
gcx resources get repositories

# Check Grafana UI
# Navigate to: Administration → Provisioning → Git Sync

Set up Git Sync with Terraform

Tue, 03 Nov 2026 16:35:21 +0000

Set up Git Sync with Terraform

You can configure Git Sync via the Grafana provisioning app platform using Terraform.

To do so, follow these steps:

Before you begin

Before you begin, make sure to have the following:

A Grafana Cloud account or an on-prem Grafana instance.
Administrator permissions in your Grafana stack/instance.
Terraform 1.11 or later installed on your machine. Refer to the Terraform install documentation to learn more.

You need the three files described in this document to set up Git Sync with Terraform:

Save all of them in the same directory.

Configure the Grafana Terraform provider

Configure the Grafana Terraform provider with the authentication required to set up Git Sync.

Create a service account and token in Grafana. For more information refer to Service account tokens or Create and manage a Grafana Cloud stack using Terraform.
Make sure that the token has the Admin or the Provisioning:Repositories writer permission.

Create a file named main.tf and add the following:

   terraform {
     required_providers {
       grafana = {
         source  = "grafana/grafana"
         version = ">= 4.28.1"
       }
     }
   }

   provider "grafana" {
     url = "https://'<STACK_URL>'.grafana.net/"
     auth = "<YOUR_SERVICE_ACCOUNT_TOKEN>"
     stack_id = "<YOUR_STACK_ID>"
   }

Replace the following field values:

<STACK_URL>: The URL of your Grafana stack. For example, https://my-stack.grafana.net/.
<YOUR_SERVICE_ACCOUNT_TOKEN>: The service account token that you created, or <USERNAME>:<PASSWORD> for basic auth.
<YOUR_STACK_ID>: The Grafana stack ID, if you’re using a Grafana Cloud stack.

Caution
Don’t use your Grafana Cloud provider settings in this configuration.

The Git Sync resources are App Platform resources and talk directly to the Grafana stack’s API. Configure the Terraform provider with url and auth, not cloud_api_url nor cloud_access_policy_token. If you’re using Grafana Cloud, set stack_id to your stack ID.

Create the resources to use Git Sync

You need to create one or two resources to configure and manage Git Sync:

The connection resource configures your Git provider credentials. This resource is only needed if you’re connecting with OAuth or GitHub App.
The repository resource configures the Git repository to sync Grafana resources with.

For better understanding of the required resources, refer to Git Sync key concepts.

Configure the Connection resource

The Connection resource manages the Git Sync connections used by repositories for provider authentication.

resource "grafana_apps_provisioning_connection_v0alpha1" "example" {
  metadata {
    uid = "my-connection"
  }

  spec {
    title       = "My Connection"
    description = "Connection used by a folder-scoped Git Sync repository"
    type        = "<CONNECTION_TYPE>" # githubOAuth, githubEnterpriseOAuth, gitlabOAuth, bitbucketOAuth, or gitOAuth
    url         = "https://connection.com"
  }

  secure {
    private_key = {
      create = filebase64("${path.module}/private-key.pem")
    }
  }
  secure_version = 1
}

Replace the following field values:

<CONNECTION_TYPE>: The Git provider type. Possible values are githubOAuth, githubEnterpriseOAuth, gitlabOAuth, bitbucketOAuth, and gitOAuth.

For more details, optional fields, and examples, refer to Connection resource in the Terraform registry.

Configure the Repository resource

The Repository resource manages your Git Sync repositories for provisioning dashboards and related resources.

For example, for a GitHub repository with token authentication:

resource "grafana_apps_provisioning_repository_v0alpha1" "example" {
  metadata {
    uid = "my-github-folder-repo"
  }

  spec {
    title       = "My GitHub Folder Repository"
    description = "Folder-scoped GitHub repository authenticated directly with a token"
    type        = "github"

    workflows = "<YOUR-WORKFLOWS>" # For example, ["write", "branch"]

    sync {
      enabled          = "<SYNC_ENABLED>"
      target           = "<YOUR_SYNC_TARGET>"
      interval_seconds = "<SYNC_INTERVAL>"
    }

    github {
      url    = "<YOUR_GITHUB_REPO_URL>"
      branch = "<SYNC_BRANCH>"
      path   = "grafanatftest"
    }

    webhook {
      base_url = "https://grafana.example.com"
    }
  }

  secure {
    token = {
      create = "replace-me"
    }
  }
  secure_version = 1
}

Replace the following field values:

<YOUR_WORKFLOWS>: Array with the workflows you want Git Sync to use. For example, ["write", "branch"]. Use write to allow direct commits, branch to force using PRs, or leave blank if the repository is read-only.
<SYNC_ENABLED>: Whether you want to enable automatic synchronization. Allowed values are true and false.
<YOUR_SYNC_TARGET>: Where you want to place your provisioned resources. Git Sync supports two sync targets: folder (default) creates a folder named after the repository and places synced resources inside it, while folderless places synced resources at the top level without creating a wrapper folder. Refer to Sync targets for details.
<SYNC_INTERVAL>: How often your Grafana instance automatically pulls updates from the folder managed with Git Sync. The default value is 300 seconds in Grafana Cloud, and 60 seconds in Grafana OSS/Enterprise.
<YOUR_GITHUB_REPO_URL>: The repository you want to synchronize using Git Sync. For example, https://github.com/example/grafana-dashboards.
<SYNC_BRANCH>: The branch where you want to perform the sync. For example, main.

For more details and examples such as a GitHub repository via GitHub App Connection or a GitLab/Bitbucket repository with a token authentication, refer to Repository resource in the Terraform registry.

Instantaneous pulling and dashboard previews

Wed, 28 Oct 2026 09:22:36 +0000

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.

Capability	Benefit	Requires
A table summarizing changes to your pull request	A convenient way to save changes back to GitHub	Webhooks configured
A dashboard preview image to a PR	A snapshot of dashboard changes to a pull request outside Grafana	Image renderer and webhooks configured

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:

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.
After you have the public URL, add it to your Grafana configuration file:
ini
```
[server]
root_url = https://<PUBLIC_DOMAIN>
```
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

Caution
Available in Grafana OSS and Grafana Enterprise only.

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: