grafana/docs/sources/as-code/observability-as-code/git-sync/git-sync-setup/set-up-code.md

description	keywords	labels	title	weight	canonical	aliases
Instructions for setting up Git Sync as code, so you can provision Git repositories for use with Grafana.	set up git integration git sync github as code	products enterprise oss cloud	Set up Git Sync as code	200	https://grafana.com/docs/grafana/latest/as-code/observability-as-code/git-sync/git-sync-setup/set-up-code	../../../observability-as-code/provision-resources/git-sync-setup/ ../provision-resources/git-sync-setup/

Set up Git Sync as code

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

Git Sync is now GA for Grafana Cloud, OSS and Enterprise. Refer to Usage and performance limitations to understand usage limits for the different tiers.

Contact Grafana for support or to report any issues you encounter and help us improve this feature.

{{< /admonition >}}

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

Set up Git Sync as code with the Grafana CLI

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

1. Understand Usage and performance limitations
2. Create the connection and repository CRDs
3. Push the CRDs to Grafana
4. Manage repository resources
5. Verify setup

Create the resources CRDs

If you're connecting with any of the supported Git providers using a Personal Access Token, you need to create a repository resource to define the connection between your repositories and your Grafana instance.

If you're connecting to Git Sync with GitHub App, in addition to the repository resource you need to create a connection resource as well.

Create the 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>'

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 Private Key

Create the repository resource

Next, create a repository.yaml file defining your Git Sync configuration. Depending on your Git provider and authentication method, add your Personal Access Token information or the connection name.

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

# Git Sync for GitHub:
spec:
  type: github
  github:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: grafana/
# GitHub App connection only:
  connection:
    name: '<GITHUB_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" }

Replace the placeholders with your values:

• <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
• <GIT_PAT>: Git provider Personal Access Token

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

Only target: folder is currently supported for Git Sync.

{{< /admonition >}}

Configuration parameters

The following configuration parameters are available:

Field	Description
metadata.name	Unique identifier for this repository resource
spec.title	Human-readable name displayed in Grafana UI
spec.type	Repository type (github)
spec.github.url	GitHub repository URL
spec.github.branch	Branch to sync
spec.github.path	Directory path containing dashboards
spec.github.generateDashboardPreviews	Generate preview images (true/false)
spec.sync.enabled	Enable synchronization (true/false)
spec.sync.intervalSeconds	Sync interval in seconds
spec.sync.target	Where to place synced dashboards (folder)
spec.workflows	Enabled workflows: write (direct commits), branch (PRs)
secure.token.create	GitHub Personal Access Token

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.

Push the repository configuration. If you're using GitHub App to connect Git Sync, push the connection resource configuration file as well.

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:

1. Create the required resources (repository and, for GitHub App, connection)
2. Connect to your GitHub repository
3. Pull dashboards from the specified path
4. 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