Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Как кодbreadcrumb arrow Наблюдаемость как кодbreadcrumb arrow Синхронизация Gitbreadcrumb arrow Настройка Git Sync

Настройка Git Sync

Note

Возможности Git Sync постоянно развиваются. Обратитесь в Grafana, чтобы получить поддержку, сообщить о проблемах и помочь нам улучшить эту функцию.

Чтобы настроить Git Sync и синхронизировать дашборды и папки Grafana с репозиторием GitHub, выполните следующие шаги:

  1. Внимательно прочитайте раздел Прежде чем начать.
  2. Настройте Git Sync через интерфейс, с помощью Terraform или как код.
  3. После настройки проверьте, что дашборды синхронизированы корректно.
  4. При желании вы также можете расширить Git Sync с помощью webhooks и рендеринга изображений.

Кроме того, файловое выделение ресурсов (file provisioning) on-prem в Grafana позволяет подключать ресурсы, включая папки и JSON-файлы дашбордов, хранящиеся в локальной файловой системе. Подробности см. в разделе Выделение ресурсов on-prem.

Настройка Git Sync через интерфейс

Чтобы настроить Git Sync из интерфейса Grafana, выполните следующие шаги:

  1. Войдите на свой сервер Grafana под учётной записью с установленным флагом Grafana Admin.
  2. Выберите Administration > General > Provisioning в меню слева, чтобы открыть экран настройки Git Sync. Если у вас уже есть активное подключение Git Sync, перейдите на вкладку Get started.
  3. Выберите провайдера, чтобы начать новую настройку Git Sync: GitHub, GitLab, Bitbucket или Pure Git.
  4. Настройте репозиторий выделения.
  5. Выберите, что синхронизировать с Grafana.
  6. Синхронизируйте с внешним хранилищем.
  7. Выберите дополнительные настройки.

Выбор провайдера

Git Sync доступен для любого Git-провайдера через тип репозитория Pure Git, а также имеет специальные расширенные интеграции для GitHub, GitHub Enterprise, GitLab и Bitbucket. Подробности см. в разделе Совместимые провайдеры.

Выберите один из следующих вариантов, чтобы продолжить:

Настройка GitHub

Если вы хотите настроить Git Sync для публичного облачного GitHub, вы можете подключиться с помощью Personal Access Token или через GitHub App. Что бы вы ни выбрали, убедитесь, что у вас есть следующие права:

  • Administration: разрешение на чтение
    • Это позволяет проверять правила защиты веток применительно к настроенной ветке, когда пользователи могут пушить в неё напрямую
    • В будущем это может использоваться для проверки других настроек репозитория и упрощения процесса настройки
  • Contents: разрешение на чтение и запись
  • Metadata: разрешение на чтение
  • Pull requests: разрешение на чтение и запись
  • Webhooks: разрешение на чтение и запись

Информацию о том, как настроить каждый из способов, см. в следующих разделах:

  • Создание нового мелкогранулярного personal access token. Для настройки репозитория вам нужен Personal Access Token из роли Admin. GitHub выдаёт разрешение Webhooks: Read and write только администраторам репозитория, поэтому токены, созданные пользователями без прав администратора, не смогут управлять webhooks, на которые Git Sync опирается для мгновенных обновлений и предпросмотров pull request.
  • Создание GitHub App.

Подключение с помощью GitHub Personal Access Token

Заполните следующие поля:

  1. Вставьте Repository URL вашего репозитория GitHub в текстовое поле.
  2. Вставьте ваш Personal Acccess Token.

Выберите Configure repository, чтобы настроить папку выделения.

Подключение с помощью GitHub App

Если вы хотите настроить Git Sync для GitHub и аутентифицироваться с помощью GitHub App:

  • Если у вас уже подключён существующий GitHub App, выберите Choose an existing app.

    1. В раскрывающемся меню выберите подключение, которое хотите использовать.
    2. Вставьте Repository URL вашего репозитория GitHub в текстовое поле.

  • Если вы хотите подключиться с помощью нового GitHub App, выберите Connect to a new app.

    1. Заполните следующие поля:
      • ID GitHub App, который хотите использовать.
      • GitHub Installation ID.
      • Private Key.
    2. Вставьте Repository URL вашего репозитория GitHub в текстовое поле.

Выберите Configure repository, чтобы настроить папку выделения.

Настройка GitHub Enterprise

Аналогично вы можете подключиться к GitHub Enterprise Server или GitHub Enterprise Cloud с помощью Personal Access Token или через GitHub App. Описание необходимых разрешений см. в разделе Настройка GitHub.

Подключение с помощью GitHub Personal Access Token

Заполните следующие поля:

  1. Вставьте Repository URL вашего репозитория GitHub в текстовое поле.
  2. Вставьте ваш Personal Acccess Token.

Выберите Configure repository, чтобы настроить папку выделения.

Подключение с помощью GitHub App

Если вы хотите настроить Git Sync для GitHub Enterprise и аутентифицироваться с помощью GitHub App:

  • Если у вас уже подключён существующий GitHub App, выберите Choose an existing app.

    1. В раскрывающемся меню выберите подключение, которое хотите использовать.
    2. Вставьте Repository URL вашего репозитория GitHub в текстовое поле.

  • Если вы хотите подключиться с помощью нового GitHub App, выберите Connect to a new app.

    1. Заполните следующие поля:
      • ID GitHub App, который хотите использовать.
      • GitHub Installation ID.
      • Private Key.
      • URL вашего экземпляра GitHub Enterprise.
        • Для GitHub Enterprise Cloud он выглядит как https://<enterprise-slug>.ghe.com.
        • Для GitHub Enterprise Server — ваш собственный URL.
    2. Вставьте Repository URL вашего репозитория GitHub в текстовое поле.

Выберите Configure repository, чтобы настроить папку выделения.

Настройка GitLab

Если вы хотите настроить Git Sync для GitLab, вам нужен GitLab Personal Access Token. Чтобы создать его, войдите в GitLab и создайте токен со следующими разрешениями:

  • Repository: разрешение на чтение и запись
  • User: разрешение на чтение
  • API: разрешение на чтение и запись

Если вы используете токен от service account, вам нужно добавить service account в проект GitLab в качестве участника, чтобы избежать проблем с аутентификацией.

После создания токена вернитесь в Grafana и заполните следующие поля:

  1. Вставьте токен в текстовое поле Project Access Token.
  2. Вставьте Repository URL вашего репозитория GitLab в текстовое поле.

Выберите Configure repository, чтобы настроить папку выделения.

Настройка Bitbucket

Если вы хотите настроить Git Sync для Bitbucket, вам нужен API-токен Bitbucket с областями действия (scopes). Чтобы создать его, войдите в Bitbucket и создайте API-токен со следующими разрешениями:

  • Repositories: разрешение на чтение и запись
  • Pull requests: разрешение на чтение и запись
  • Webhooks: разрешение на чтение, запись и удаление

Вернитесь в Grafana и заполните следующие поля:

  1. Вставьте токен в текстовое поле API Token.

  2. Вставьте Repository URL вашего репозитория Bitbucket в текстовое поле.

    Используйте Git clone URL репозитория, а не URL, который отображается в адресной строке браузера при просмотре репозитория. Чтобы найти его, выберите Clone в Bitbucket и скопируйте HTTPS URL. Clone URL заканчивается на .git, а его формат зависит от развёртывания Bitbucket:

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

    Tip

    Если Grafana возвращает ошибку ls-refs при подключении к репозиторию, проверьте, что вы указали clone URL, а не URL из браузера.

Выберите Configure repository, чтобы настроить папку выделения.

Настройка Pure Git

Если вы используете другого Git-провайдера, для настройки подключения нужно воспользоваться вариантом Pure Git с Personal Access Token:

  1. Вставьте access token или пароль репозитория Git, который хотите синхронизировать, в поле Access Token.
  2. Введите Username. Git Sync будет использовать это имя для доступа к репозиторию Git.
  3. Вставьте Repository URL вашего репозитория Git в текстовое поле.

Выберите Configure repository, чтобы настроить папку выделения.

Настройка репозитория выделения

После настройки аутентификации подключения перейдите к вводу сведений о репозитории, который хотите использовать для выделения ресурсов:

  1. Введите Branch, которую будете использовать для выделения. Значение по умолчанию — main.
  2. При желании можно указать Path к подкаталогу, в котором хранятся ваши дашборды.

Выберите Choose what to synchronize, чтобы проверить подключение к репозиторию и продолжить настройку.

Выбор объектов синхронизации

Далее синхронизируйте внешние ресурсы, указанные на предыдущем шаге, с вашим экземпляром Grafana. Вы можете хранить эти выделенные ресурсы в Grafana — либо в корне выделенной папки, либо в новой папке, — не затрагивая остальную часть экземпляра.

Чтобы настроить синхронизацию:

  1. Выберите, хотите ли вы хранить синхронизируемые ресурсы в новой папке или на корневом уровне в Grafana. Подробнее об этих вариантах см. в разделе Цели синхронизации. Интерфейс предоставляет информацию о ресурсах, доступных для синхронизации.
  2. Введите Display name для подключения к репозиторию. Все синхронизируемые ресурсы из этого подключения Git Sync будут отображаться в интерфейсе Grafana под этим именем.
  3. Нажмите Synchronize with external storage, чтобы продолжить.
  4. Эту процедуру можно повторить максимум для 10 подключений.

При желании вы можете экспортировать любые неуправляемые ресурсы в выделенную папку. Как это сделать, см. в разделе Синхронизация с внешним хранилищем.

Выберите Choose additional settings, чтобы продолжить настройку.

Синхронизация с внешним хранилищем

Чтобы продолжить синхронизацию:

  1. Просмотрите известные ограничения.
  2. Вы можете увидеть экспериментальный флажок Migrate existing resources, который позволяет перенести неуправляемые дашборды в выделенную папку. Если вы его не видите, обратитесь к разделу Экспорт невыделенных ресурсов из Grafana, чтобы узнать, как перенести существующие ресурсы.
  3. Нажмите Begin synchronization, чтобы создать подключение Git Sync. Когда процесс завершится, вы увидите сводку синхронизированных ресурсов.

Нажмите Choose additional settings для завершающих шагов настройки.

Выбор дополнительных настроек

На этом последнем шаге вы можете настроить дополнительные параметры Git Sync. Когда закончите, нажмите Finish, чтобы завершить настройку.

Интервал синхронизации

Используйте настройку Sync interval (seconds), чтобы указать, как часто ваш экземпляр Grafana должен автоматически забирать обновления из папки, управляемой Git Sync. Значение по умолчанию — 300 секунд в Grafana Cloud и 60 секунд в Grafana OSS/Enterprise.

Дополнительные настройки

Вы также можете выбрать следующие дополнительные настройки:

  • Установите флажок Read only, чтобы гарантировать, что ресурсы нельзя изменить в Grafana.
  • Установите флажок Enable pull request option when saving, чтобы выбирать, открывать ли pull request при сохранении изменений. Если репозиторий не допускает прямых изменений в основной ветке, pull request всё равно может потребоваться.
  • Установите флажок Enable push to configured branch, чтобы разрешить прямые коммиты в настроенную ветку.
  • Установите флажок Generate dashboards previews, чтобы создавать ссылки на предпросмотр для pull request. Для этой опции требуется рендеринг изображений и активация публичного доступа.

Определившись с этими настройками, вы можете настроить Webhooks или проверенную учётную запись с помощью Commit options. Либо, если вы хотите, чтобы ваши коммиты оставались неподписанными, нажмите Save, чтобы продолжить.

Опции webhooks

В меню Webhook options вы можете ввести URL, чтобы переопределить автоматически определённый URL, используемый для регистрации webhooks. Убедитесь, что у вас есть соответствующие разрешения для настройки webhooks и управления ими.

Вы также можете установить флажок Disable webhook integration. Когда он установлен, Grafana не регистрирует и не получает события webhook, а вместо этого опрашивает репозиторий через заданный интервал. Используйте это, когда ваш экземпляр Grafana недоступен из публичного интернета.

Git-провайдеры ограничивают количество webhooks, разрешённых в их репозиториях. Подробнее и о том, как действовать при достижении этих ограничений, см. в разделе Ограничения webhooks.

Настройки подписанных коммитов

Начиная с Grafana 13.1.0 вы можете настроить проверенную учётную запись с ключом подписи, что позволяет требовать от пользователей подписывать коммиты, чтобы ваш Git-провайдер помечал их как Verified. Git Sync поддерживает ключи GPG, SSH и S/MIME.

Начиная с Grafana 13.2.0 все коммиты по умолчанию используют вошедшего в систему пользователя Grafana как автора коммита. Подробнее см. в разделе Параметры автора.

На данный момент Git Sync не поддерживает:

  • Ключи, защищённые парольной фразой.
  • Проверку отдельных учётных записей.

Следуйте мастеру в интерфейсе, чтобы заполнить необходимые поля для настройки любого из этих вариантов, а подробности см. в разделах ниже.

Предварительные требования

Чтобы реализовать подписанные коммиты, убедитесь, что вы настроили специальную учётную запись для проверки в вашем Git-провайдере. Для настройки проверки вам понадобятся ключ подписи, имя и адрес электронной почты этой учётной записи.

Подробнее о том, как создать ключи для аутентификации в Git, см. в официальной документации:

Пример: подпись коммитов с помощью SSH-ключа

Чтобы требовать подписанные коммиты с использованием SSH-ключа, выполните следующие шаги:

  1. Откройте меню Commit options (advanced).
  2. В разделе Commit signing выберите SSH.
  3. Заполните следующие поля:
    • Приватный ключ учётной записи, подлежащей проверке.
    • Имя подписывающего, которое будет отображаться в вашем Git-провайдере.
    • Адрес электронной почты подписывающего, который должен совпадать с указанным в ключе подписи.
  4. Нажмите Save.

После завершения настройки ключа все коммиты, которые делают ваши пользователи в выделенную папку, будут отображаться как Verified.

Параметры автора

Начиная с Grafana 13.2.0 вы можете добавлять информацию об авторе в свои коммиты.

Авторство в неподписанных коммитах

Если вы не включаете подпись коммитов:

  • Если вы добавляете переопределение автора, author каждого коммита будет настроенным переопределением.
  • Если вы не выбираете переопределение автора, в качестве автора коммита будут использоваться имя и адрес электронной почты вошедшего в систему пользователя Grafana.

Авторство в подписанных коммитах

Если вы включаете подпись коммитов:

  • Если вы включаете подписывающего как автора коммита, Git Sync будет использовать имя и адрес электронной почты подписывающего как автора всех коммитов.
  • Если вы не включаете подписывающего как автора коммита, в качестве author коммита будут использоваться имя и адрес электронной почты вошедшего в систему пользователя Grafana, а committer будет настроенным подписывающим.

Проверка дашбордов в Grafana

Убедитесь, что синхронизированные дашборды доступны в указанном вами месте:

  1. Перейдите в Dashboards.
  2. Найдите название дашборда в столбце Name.

Теперь, когда ваши ресурсы синхронизированы, вы можете изменить имя, сменить ветку и создать для неё pull request (PR). Подробнее см. в разделе Работа с выделенными репозиториями в Git Sync.

Обновление или удаление синхронизированных ресурсов

Чтобы обновить или удалить конфигурацию репозитория после завершения настройки:

  1. Войдите на свой сервер Grafana под учётной записью с установленным флагом Grafana Admin.
  2. Выберите Administration > General > Provisioning.
  3. Перейдите на вкладку Repositories и найдите репозиторий, который хотите изменить.
  4. Выберите Settings, чтобы открыть экран Configure repository:
  • Чтобы изменить конфигурацию, обновите любые настройки и выберите Save.
  • Чтобы удалить репозиторий, нажмите Delete. Вы можете либо сохранить синхронизированные ресурсы, либо удалить их.

Дальнейшие шаги

Вы успешно настроили Git Sync для управления дашбордами Grafana через систему контроля версий. Теперь ваши дашборды синхронизированы с репозиторием GitHub, что обеспечивает совместную разработку и отслеживание изменений.

Чтобы узнать больше об использовании Git Sync, обратитесь к следующим документам: