docs/sources/as-code/observability-as-code/git-sync/permissions-grafana.md
{{< admonition type="note" >}}
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 >}}
For Git Sync you need to configure permissions at two layers to function correctly:
Git Sync integrates with the Grafana standard role-based permission model, which has three levels:
Admin, Editor, or Viewer role. Refer to Roles and permissions for more details.{{< admonition type="note" >}}
Dashboard-level permissions override folder-level permissions, which override organization-level roles.
{{< /admonition >}}
The following applies for Git Sync:
If you apply org-level permissions, users can do the following with Git Sync:
Users with the Admin role can set up and manage Git Sync repositories and connections.
{{< admonition type="note" >}} In Grafana Cloud, the equivalent role is Grafana Cloud Admin or Admin at the organization level. {{< /admonition >}}
Capabilities:
Users with the Viewer role can view provisioned resources. Their access to specific dashboards and folders depends on the permissions assigned to them.
Organization-level capabilities:
provisioning.settings:read permissionResource access depends on folder and dashboard permissions:
Users with the Editor role can work with provisioned dashboards and folders. Their specific capabilities depend on the folder-level and dashboard-level permissions assigned to them.
Organization-level capabilities:
Resource access depends on folder/dashboard permissions:
Editors don't need access to the Provisioning admin UI or repository configuration. Refer to Configure folder and dashboard permissions and Configure fine-grained access control (RBAC) for details.
Folder-level role permissions determine who can view, edit, or delete provisioned resources.
These roles grant Grafana permissions (dashboards:read, dashboards:write, folders:create...) that are checked when users interact with provisioned resources through the Git Sync files endpoint. Dashboards within a provisioned folder inherit the folder's permissions.
When Git Sync creates a provisioned folder, it assigns these default permissions:
| Grafana Role | Folder Permission |
|---|---|
| Admin | Admin |
| Editor | Editor |
| Viewer | Viewer |
Folder-level Viewer users:
Folder-level Editor users:
Viewer permissionsEditor saves dashboard changes, Git Sync automatically commits the changes to Git, or creates a pull request if branch protection is enabledFolder-level Admin users:
Editor permissions{{< admonition type="note" >}}
To safely modify permissions, each provisioned folder should include a .folder.json metadata file with the folder's UID. Without this file, folder permissions may be lost if the folder is moved to a different path in the Git repository.
For folders created from the Grafana UI, the metadata file is added automatically. If your folder is missing the metadata file, the UI shows a warning with instructions on how to add it. {{< /admonition >}}
You can customize folder permissions using:
If you're a Grafana Enterprise or Grafana Cloud user with RBAC enabled, Git Sync provides fine-grained permissions that allow more granular control over Git Sync operations. You can create custom roles that combine Git Sync permissions in different ways. Refer to Role-Based Access Control documentation for instructions on creating and managing custom roles.
Understanding which permissions each basic role receives helps you create custom roles or understand exactly what access users have. The tables below show which Git Sync permissions are granted to each role by default.
{{< admonition type="note" >}}
The provisioning.settings:read permission is granted to all roles (Viewer and above) and allows viewing Git Sync system settings, which is necessary for the UI to display properly. This does not grant access to modify settings or manage repositories.
{{< /admonition >}}
Users with the Admin role receive full access to Git Sync infrastructure:
| Permission Category | Specific Permissions | What This Allows |
|---|---|---|
| Repositories | provisioning.repositories:create | |
provisioning.repositories:read | ||
provisioning.repositories:write | ||
provisioning.repositories:delete | Create new repositories | |
| View repository configurations | ||
| Update repository settings (branch, path, interval) | ||
| Delete repositories | ||
| Connections | provisioning.connections:create | |
provisioning.connections:read | ||
provisioning.connections:write | ||
provisioning.connections:delete | Create Git provider connections | |
| View connection details | ||
| Update connection settings | ||
| Delete connections | ||
| Jobs | provisioning.jobs:create | |
provisioning.jobs:read | ||
provisioning.jobs:write | ||
provisioning.jobs:delete | Trigger manual syncs | |
| View sync jobs | ||
| Modify sync job settings | ||
| Cancel/delete sync jobs | ||
| History & Monitoring | provisioning.historicjobs:read | |
provisioning.stats:read | View sync job history | |
| View Git Sync statistics and metrics | ||
| Settings | provisioning.settings:read | View Git Sync system settings |
Users with the Editor role can manage sync operations but not infrastructure configuration:
| Permission Category | Specific Permissions | What This Allows |
|---|---|---|
| Jobs | provisioning.jobs:create | |
provisioning.jobs:read | ||
provisioning.jobs:write | ||
provisioning.jobs:delete | Trigger manual syncs | |
| View sync jobs | ||
| Modify sync job settings | ||
| Cancel/delete sync jobs | ||
| Read-Only Access | provisioning.repositories:read | |
provisioning.settings:read | View repository configurations | |
| View Git Sync settings |
Editors can access resources based on the folder/dashboard assignments:
dashboards:create, dashboards:read, dashboards:write, dashboards:delete - On folders/dashboards where assigned Folder Editor or Dashboard Editorfolders:create, folders:read, folders:write, folders:delete - On folders where assigned Folder EditorUsers with Viewer role have read-only access to Git Sync:
| Permission Category | Specific Permissions | What This Allows |
|---|---|---|
| Read-Only Access | provisioning.repositories:read | |
provisioning.settings:read | View repository configurations | |
| View Git Sync settings (required for UI) |
Viewers can access resources based on the folder/dashboard assignments:
dashboards:read - On folders/dashboards where assigned Folder Viewer or Dashboard Viewerfolders:read - On folders where assigned Folder ViewerProvisioned dashboards and folders use the Grafana standard permission model. To modify provisioned resources, you will need permissions over your dashboard and folder.
The following applies for Git Sync:
dashboards:* and folders:* permissions to work with provisioned resourcesEditors and Viewers need provisioning.settings:read and provisioning.repositories:read to view Git Sync configurationAfter you've configured your Grafana permissions, set up the appropriate permissions at your Git provider to write changes. Repository protection settings control write access, branch protection rules, and code review requirements.
For detailed information about configuring repository write access and branch protection, refer to Repository protection for Git Sync.
Cause: User lacks Editor or Admin permission on the provisioned folder.
Solution:
Cause: The Git provider credentials lack the required permissions.
Solution:
Cause: Branch protection is not configured at the Git provider.
Solution: Enable branch protection rules at your Git provider to enforce pull request workflows or in your Grafana repository settings. Refer to your Git provider's documentation for instructions on configuring branch protection.