Set up Git Sync

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

Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

{{< /admonition >}}

To set up Git Sync and synchronize your Grafana dashboards and folders with a GitHub repository, follow these steps:

1. Read Before you begin carefully.
2. Set up Git Sync using the UI, with Terraform, or as code.
3. After setup, check your dashboards have been synced correctly.
4. Optionally, you can also extend Git Sync with webhooks and image rendering.

Alternatively, on-prem file provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system. Refer to Provision resources on-prem for more details.

Set up Git Sync using the UI

To set up Git Sync from the Grafana UI, follow these steps:

1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
2. Select Administration > General > Provisioning in the left-side menu to access the Git Sync configuration screen. If you already have an active Git Sync connection, go to the Get started tab.
3. Select your provider to start a new Git Sync setup: GitHub, GitLab, Bitbucket, or Pure Git.
4. Configure the provisioning repository.
5. Choose what content to sync with Grafana.
6. Synchronize with external storage.
7. Choose additional settings.

Select your provider

Git Sync is available for any Git provider through a Pure Git repository type, and has specific enhanced integrations for GitHub, GitHub Enterprise, GitLab and Bitbucket. Refer to Compatible providers for more details.

Select any of these options to proceed:

• GitHub
• GitHub Enterprise (Server and Cloud)
• GitLab
• Bitbucket
• Pure Git

Configure with GitHub

If you want to configure Git Sync for public cloud GitHub, you can connect using a Personal Access Token or with GitHub App. Whichever you choose, make sure you have the following permissions:

• Administration: Read-only permission
  • This enables validation of branch protection rules against the configured branch when users can push directly to it
  • In the future, it might be used 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

For information on how to set up each method, refer to:

• Create a new fine-grained personal access token. You need a Personal Access Token from an Admin role to set up the repository. GitHub only grants the Webhooks: Read and write permission to repository admins, so tokens created by non-admin users can't manage the webhooks Git Sync relies on for instantaneous updates and pull request previews.
• Create a GitHub App.

Connect with a GitHub Personal Access Token

Fill in the following fields:

1. Paste the Repository URL for your GitHub repository into the text box.
2. Paste your Personal Acccess Token.

Select Configure repository to set up your provisioning folder.

Connect with GitHub App

If you want to configure Git Sync for GitHub and authenticate with GitHub App:

• If you already have an existing GitHub App connected, select Choose an existing app.

  1. From the drop-down menu, select the connection you want to use.
  2. Paste the Repository URL for your GitHub repository into the text box.

• If you want to connect using a new GitHub App, select Connect to a new app.

  1. Type in the following fields:
     • The ID of the GitHub App you want to use.
     • The GitHub Installation ID.
     • The Private Key.
  2. Paste the Repository URL for your GitHub repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure with GitHub Enterprise

Similarly, you can connect to GitHub Enterprise Server or GitHub Enterprise Cloud using a Personal Access Token or with GitHub App. Refer to Configure with GitHub for details on the required permissions.

Connect with a GitHub Personal Access Token

Fill in the following fields:

1. Paste the Repository URL for your GitHub repository into the text box.
2. Paste your Personal Acccess Token.

Select Configure repository to set up your provisioning folder.

Connect with GitHub App

If you want to configure Git Sync for GitHub Enterprise and authenticate with GitHub App:

• If you already have an existing GitHub App connected, select Choose an existing app.

  1. From the drop-down menu, select the connection you want to use.
  2. Paste the Repository URL for your GitHub repository into the text box.

• If you want to connect using a new GitHub App, select Connect to a new app.

  1. Type in the following fields:
     • The ID of the GitHub App you want to use.
     • The GitHub Installation ID.
     • The Private Key.
     • The URL of your GitHub Enterprise instance.
       • For GitHub Enterprise Cloud, it looks like https://<enterprise-slug>.ghe.com.
       • For GitHub Enterprise Server, your custom URL.
  2. Paste the Repository URL for your GitHub repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure with GitLab

If you want to configure Git Sync for GitLab, you need a GitLab Personal Access Token. To create one, sign in to GitLab and create a token with these permissions:

• Repository: Read and write permission
• User: Read only permission
• API: Read and write permission

If you're using a token from a service account, you need to add the service account to the GitLab project as a member to avoid authentication issues.

After creating the token, return to Grafana and fill in the following fields:

1. Paste the token into the Project Access Token text box.
2. Paste the Repository URL for your GitLab repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure with Bitbucket

If you want to configure Git Sync for Bitbucket, you need a Bitbucket API token with scopes. To create one, sign in to Bitbucket and create an API token with these permissions:

• Repositories: Read and write permission
• Pull requests: Read and write permission
• Webhooks: Read, write, and delete permission

Return to Grafana and fill in the following fields:

1. Paste the token into the API Token text box.

2. Paste the Repository URL for your Bitbucket repository into the text box.

   Use the Git clone URL for the repository, not the URL that appears in your browser's address bar when you view the repository. To find it, select Clone in Bitbucket and copy the HTTPS URL. The clone URL ends in .git, and its format depends on your Bitbucket deployment:

   • Bitbucket Cloud: https://bitbucket.org/<workspace>/<repository>.git
   • Bitbucket Data Center and Server: https://<bitbucket-host>/scm/<PROJECT>/<repository>.git

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

   If Grafana returns an ls-refs error when it connects to the repository, check that you entered the clone URL and not the browser URL.

   {{< /admonition >}}

Select Configure repository to set up your provisioning folder.

Configure with Pure Git

If you're using another Git provider, you need to use the Pure Git option to configure your connection with a Personal Access Token:

1. Paste the access token or password of the Git repository you want to sync in Access Token.
2. Enter a Username. Git Sync will use this name to access the Git repository.
3. Paste the Repository URL of your Git repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure the provisioning repository

After configuring your connection authentication, continue to enter the details of the repository you want to use for provisioning:

1. Enter a Branch to use for provisioning. The default value is main.
2. Optionally, you can add a Path to a subdirectory where your dashboards are stored.

Select Choose what to synchronize to have the connection to your repository verified and continue setup.

Choose what to synchronize

Next, sync the external resources you specified in the previous step with your Grafana instance. You can store these provisioned resources in Grafana, either at the root of the provisioned folder or in a new folder, without affecting the rest of your instance.

To set up synchronization:

1. Select whether you want to store synced resources in a new folder or at root level in Grafana. For more information on these options, refer to Sync targets. The UI provides information about the available resources you can sync.
2. Enter a Display name for your repository connection. All the synced resources from this Git Sync connection will appear under the this name in the Grafana UI.
3. Click Synchronize with external storage to continue.
4. You can repeat this process for up to 10 connections.

Optionally, you can export any unmanaged resources into the provisioned folder. See how in Synchronize with external storage.

Select Choose additional settings to continue setup.

Synchronize with external storage

To proceed with the sync:

1. Review the known limitations.
2. You may see the experimental checkbox Migrate existing resources, which allows you to migrate your unmanaged dashboards to the provisioned folder. If you don't, refer to Export non-provisioned resources from Grafana to learn how to migrate your existing resources.
3. Click Begin synchronization to create the Git Sync connection. When the process is completed, you'll see a summary of the synced resources.

Click Choose additional settings for the final configuration steps.

Choose additional settings

In this last step, you can configure additional options for Git Sync. When you're done, click Finish to complete the setup.

Sync interval

Use the Sync interval (seconds) setting to indicate how often you want your Grafana instance to automatically pull updates from the folder managed with Git Sync. The default value is 300 seconds in Grafana Cloud, and 60 seconds in Grafana OSS/Enterprise.

Optional settings

You can also select these optional settings:

• Check Read only to ensure resources can't be modified in Grafana.
• Check Enable pull request option when saving to choose whether to open a pull request when saving changes. If the repository does not allow direct changes to the main branch, a pull request may still be required.
• Check Enable push to configured branch to allow direct commits to the configured branch.
• Check Generate dashboards previews to create preview links for pull requests. This option requires using image rendering and activating public access.

After deciding on these options, you can chose to configure Webhooks or a verified account with the Commit options. Alternatively, if you want your your commits to remain unsigned, click Save to continue.

Webhook options

In the Webhook options menu, you can type in an URL to override the auto-detected URL used to register webhooks. Make sure you have the appropriate permissions to set up and manage webhooks.

You can also check the Disable webhook integration. When checked, Grafana doesn't register or receive webhook events, and polls the repository on an interval instead. Use this when your Grafana instance is not reachable from the public internet.

Git providers limit the amount of webhooks they allow in their repositories. Refer to Webhook limits for more information and to learn how to proceed if you reach these limits.

Signed commit options

Starting in Grafana 13.1.0, you can configure a verified account with a signing key, allowing you to enforce your users to sign commits so your Git provider can mark them as Verified. Git Sync supports GPG, SSH, and S/MIME keys.

Starting in Grafana 13.2.0, by default all commits use the signed-in Grafana user as the commit author. For more details, refer to Authoring options.

For the moment, Git Sync doesn't support:

• Passphrase-protected keys.
• Verification of individual accounts.

Follow the UI wizard to fill in the required fields to set up any of these options, and refer to the sections below for more details.

Pre-requirements

In order to implement signed commits, make sure that you set up a specific verification account in your Git provider. You'll need your account's signing key, name and email to set up verification.

For more details on how to create your keys for Git authentication, refer to the official documentation:

• GitHub: Managing commit signature verification
• GitLab: Signed commits
• Bitbucket: Controlling access to code

Example: Sign your commits with an SSH key

To enforce signed commits using an SSH key follow these steps:

1. Open the Commit options (advanced) menu.
2. Under Commit signing, select SSH.
3. Fill in the following fields:
   • The private key for the account to verify.
   • The signer's name to be displayed in your Git provider.
   • The signer's e-mail address, which must match the one in the signing key.
4. Click Save.

After completing the key configuration, any commits your users make to the provisioned folder will appear as Verified.

Authoring options

Starting in Grafana 13.2.0, you can include authoring information to your commits.

Authoring in unsigned commits

If you don't enable commit signing:

• If you add an author override, the author for every commit will be the configured override.
• If you don't select author override, the signed-in Grafana user name and email will be used as the commit author.

Authoring in signed commits

If you enable commit signing:

• If you enable the signer as the commit author, Git Sync will use the signer name and email as the author to all commits.
• If you don't enable the signer as the commit author, the signed-in Grafana user name and email will be used as the commit author, and the committer will be the configured signer.

Check your dashboards in Grafana

Make sure that your synced dashboards are available at the location that you specified:

1. Go to Dashboards.
2. Look for the name of the dashboard in the Name column.

Now that your resources are synced, you can customize the name, change the branch, and create a pull request (PR) for it. Refer to Manage provisioned repositories with Git Sync for more information.

Update or delete your synced resources

To update or delete your repository configuration after you've completed setup:

1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
2. Select Administration > General > Provisioning.
3. Go to the Repositories tab, and locate the repository you want to modify.
4. Select Settings to access the Configure repository screen:

• To modify your configuration, update any of the settings and select Save.
• To delete the repository, click Delete. You can either keep the synced resources or delete them.

Next steps

You've successfully set up Git Sync to manage your Grafana dashboards through version control. Your dashboards are now synchronized with a GitHub repository, enabling collaborative development and change tracking.

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

• Set up instantaneous pulling and dashboard previews in Pull Requests
• Work with provisioned repositories with Git Sync
• Work with provisioned dashboards
• Add existing resources to your synced folder
• Git Sync deployment scenarios