--- title: "Set up Git Sync | Grafana Cloud documentation" description: "Instructions for setting up Git Sync, so you can provision GitHub repositories for use with Grafana." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Set up Git Sync > Note > > **Git Sync is now GA for Grafana Cloud, OSS and Enterprise.** Refer to [Usage and performance limitations](/docs/grafana-cloud/as-code/observability-as-code/git-sync/usage-limits/) to understand usage limits for the different tiers. > > [Contact Grafana](/help/) for support or to report any issues you encounter and help us improve this feature. To set up Git Sync and synchronize your Grafana dashboards and folders with a GitHub repository, follow these steps: 1. Read [Before you begin](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/set-up-before/) carefully. 2. Set up Git Sync [using the UI](#set-up-git-sync-using-the-ui), with [Terraform](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/set-up-terraform/), or [as code](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/set-up-code/) 3. After setup, [verify your dashboards](#verify-your-dashboards-in-grafana). 4. Optionally, you can also [extend Git Sync with webhooks and image rendering](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/set-up-extend/). ## 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](#select-your-provider) to start a new Git Sync setup: GitHub, GitLab, Bitbucket, or Pure Git. 4. [Configure the provisioning repository](#configure-the-provisioning-repository). 5. [Choose what content to sync with Grafana](#choose-what-to-synchronize). 6. [Synchronize with external storage](#synchronize-with-external-storage). 7. [Choose additional settings](#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, GitLab and Bitbucket. Refer to [Compatible providers](/docs/grafana-cloud/as-code/observability-as-code/git-sync/usage-limits/#compatible-providers) for more details. 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](/docs/grafana-cloud/as-code/observability-as-code/provision-resources/) for more details. Select any of these options to proceed: - [GitHub](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/#configure-with-github) - [GitLab](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/#configure-with-gitlab) - [Bitbucket](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/#configure-with-bitbucket) - [Pure Git](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/#configure-with-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**. > Note > > If you’re using self-hosted GitHub servers or GitHub Enterprise refer to [Configure with Pure Git](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/#configure-with-pure-git) for instructions on how to set up Git Sync. #### Connect with a GitHub Personal Access Token If you want to configure Git Sync for GitHub and authenticate with a Personal Access Token, sign in to GitHub and [create a new fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) with these permissions: - **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 > Note > > The Personal Access Token must belong to a user with the **Admin** role on 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. Refer to [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for instructions. Return to Grafana and fill in the following fields: 1. Paste your GitHub personal access token into **Enter your access token**. 2. Paste the **Repository URL** for your GitHub repository into the text box. Select **Configure repository** to set up your provisioning folder. #### Connect with GitHub App > Note > > Refer to [Create a GitHub App](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/set-up-before/#create-a-github-app) for instructions on how to create a 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: 1. Select **Choose an existing app**. 2. Click on the existing connection you want to use, and click on **Configure repository** to proceed. 3. Paste the **Repository URL** for your GitHub repository into the text box. - If you want to connect using a new GitHub App: 1. Select **Connect to a new app**. 2. Type in the following fields: - The ID of the GitHub App you want to use - The GitHub Installation ID - The Private Key 3. Click on **Configure repository** to proceed. 4. Paste the **Repository URL** for your GitHub repository into the text box. Note that your GitHub App must have the following permissions: - **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 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](https://gitlab.com/users/sign_in) 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](https://id.atlassian.com/login?application=bitbucket) and create an API token with these permissions: - **Repositories**: Read and write permission - **Pull requests**: Read and write permission - **Webhooks**: Read and write 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 GitLab repository into the text box. 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 On this screen, you will sync the external resources you specified in the previous step with your Grafana instance. These provisioned resources will be stored in a new folder in Grafana without affecting the rest of your instance. To set up synchronization: 1. Select the external storage you want to sync with your Grafana instance. 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. > Note > > Optionally, you can export any unmanaged resources into the provisioned folder. See how in [Synchronize with external storage](#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](/docs/grafana-cloud/as-code/observability-as-code/git-sync/export-resources/) to learn how to migrate your existing resources. 3. Click **Begin synchronization** to create the Git Sync connection. 4. After the process is completed, you will 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 the **Sync interval (seconds)** to indicate how often you want your Grafana instance to pull updates from GitHub. The default value is 300 seconds in Grafana Cloud, and 60 seconds in Grafana OSS/Enterprise. 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. Select **Finish** to complete the setup. ## Verify your dashboards in Grafana To verify that your dashboards are available at the location that you specified, go to **Dashboards**. The name of the dashboard is listed in the **Name** column. Now that your dashboards have been synced from a repository, you can customize the name, change the branch, and create a pull request (PR) for it. Refer to [Manage provisioned repositories with Git Sync](/docs/grafana/next/as-code/observability-as-code/provision-resources/use-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](/docs/grafana-cloud/as-code/observability-as-code/git-sync/git-sync-setup/set-up-extend/) - [Work with provisioned repositories with Git Sync](/docs/grafana/next/as-code/observability-as-code/provision-resources/use-git-sync/) - [Work with provisioned dashboards](/docs/grafana/next/as-code/observability-as-code/provision-resources/provisioned-dashboards/) - [Git Sync deployment scenarios](/docs/grafana/next/as-code/observability-as-code/provision-resources/git-sync-deployment-scenarios/) - [Export resources](/docs/grafana/next/as-code/observability-as-code/provision-resources/export-resources/)