Documentation Grafana documentation As code and provisioning Git Sync Set up Git Sync Set up Git Sync as code

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:

1. Read Before you begin.
2. Create the connection resource
3. Create the repository resource
4. Push the resources to Grafana
5. Manage repository resources
6. Verify setup

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:

YAML Copy

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:

YAML Copy

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:

YAML Copy

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:

1. Select Administration > General > Provisioning and go to the Connections tab.
2. Select the connection and click Reauthorize.
3. 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:

YAML Copy

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

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.

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:

sh Copy

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 or OAuth, 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:

sh Copy

gcx resources get repositories

Get repository details

To get details for a specific repository:

sh Copy

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:

sh Copy

gcx resources edit repository/<REPOSITORY_NAME>

Delete the repository

To delete a repository:

sh Copy

gcx resources delete repository/<REPOSITORY_NAME>

Verify setup

Check that Git Sync is working:

sh Copy

# List repositories
gcx resources get repositories

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