Git Sync 설정

Git Sync 설정 (Set up Git Sync)

이 문서는 Grafana 대시보드와 폴더를 GitHub 저장소와 동기화하도록 Git Sync를 설정하는 전체 절차를 안내해요. UI로 설정하는 방법, provider 선택, 동기화할 내용 선택, 추가 설정, 그리고 설정 후 대시보드 확인까지 다뤄요.

출처: 문서

본문

Note Git Sync 기능은 계속 발전하고 있어요. Grafana에 문의해 지원을 받거나 만나는 문제를 보고해 주세요.

Git Sync를 설정하고 Grafana 대시보드와 폴더를 GitHub 저장소와 동기화하려면 다음 단계를 따라요:

  1. 시작하기 전에(Before you begin) 문서를 주의 깊게 읽어요.
  2. UI 사용으로, Terraform으로, 또는 코드형(as code)으로 Git Sync를 설정해요.
  3. 설정 후 대시보드가 제대로 동기화되었는지 확인해요.
  4. 선택적으로 웹훅과 이미지 렌더링으로 Git Sync 확장을 할 수도 있어요.

또한 Grafana의 온프레미스 파일 프로비저닝을 사용하면 로컬 파일 시스템에 저장된 폴더와 대시보드 JSON 파일을 포함한 리소스를 포함시킬 수 있어요. 자세한 내용은 Provision resources on-prem을 참고해요.

UI로 Git Sync 설정 (Set up Git Sync using the UI)

Grafana UI에서 Git Sync를 설정하려면 다음 단계를 따라요:

  1. Grafana Admin 플래그가 설정된 계정으로 Grafana 서버에 로그인해요.
  2. 왼쪽 메뉴에서 Administration > General > Provisioning을 선택해 Git Sync 구성 화면에 접근해요. 이미 활성화된 Git Sync 연결이 있다면 Get started 탭으로 가요.
  3. 새 Git Sync 설정을 시작하려면 provider를 선택해요: GitHub, GitLab, Bitbucket, Pure Git.
  4. 프로비저닝 저장소를 구성해요.
  5. Grafana와 동기화할 콘텐츠를 선택해요.
  6. 외부 저장소와 동기화해요.
  7. 추가 설정을 선택해요.

provider 선택 (Select your provider)

Git Sync는 Pure Git 저장소 유형을 통해 모든 Git provider에서 사용할 수 있으며, GitHub, GitHub Enterprise, GitLab, Bitbucket에 대해 특화된 강화 통합을 제공해요. 자세한 내용은 호환 provider(Compatible providers)를 참고해요. 계속하려면 다음 옵션 중 하나를 선택해요:

GitHub로 구성 (Configure with GitHub)

퍼블릭 클라우드 GitHub용 Git Sync를 구성하려면 Personal Access Token 또는 GitHub App으로 연결할 수 있어요. 무엇을 선택하든 다음 권한이 있는지 확인해요:

  • Administration: 읽기 전용(Read-only) 권한 — 사용자가 구성된 브랜치에 직접 푸시할 수 있을 때 해당 브랜치에 대한 브랜치 보호 규칙 검증을 가능하게 해요. 향후에는 다른 저장소 설정을 확인하고 설정 과정을 더 매끄럽게 만드는 데 사용될 수도 있어요.
  • Contents: 읽기·쓰기 권한
  • Metadata: 읽기 전용 권한
  • Pull requests: 읽기·쓰기 권한
  • Webhooks: 읽기·쓰기 권한

각 방법 설정 방법은 다음을 참고해요:

  • 새 fine-grained personal access token 만들기 — 저장소를 설정하려면 Admin 역할의 Personal Access Token이 필요해요. GitHub는 Webhooks: Read and write 권한을 저장소 관리자에게만 부여하므로, 비관리자 사용자가 만든 토큰은 Git Sync가 즉시 업데이트와 풀 리퀘스트 프리뷰에 의존하는 웹훅을 관리할 수 없어요.
  • GitHub App 만들기.

GitHub Personal Access Token으로 연결 (Connect with a GitHub Personal Access Token)

다음 필드를 입력해요:

  1. GitHub 저장소의 Repository URL을 텍스트 상자에 붙여넣어요.
  2. Personal Access Token을 붙여넣어요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

GitHub App으로 연결 (Connect with GitHub App)

GitHub용 Git Sync를 구성하고 GitHub App으로 인증하려면:

  • 이미 연결된 GitHub App이 있다면 Choose an existing app을 선택해요. 드롭다운 메뉴에서 사용할 연결을 선택하고, GitHub 저장소의 Repository URL을 텍스트 상자에 붙여넣어요.
  • 새 GitHub App으로 연결하려면 Connect to a new app을 선택해요. 다음 필드를 입력해요: 사용할 GitHub App의 ID, GitHub Installation ID, Private Key. 그리고 GitHub 저장소의 Repository URL을 텍스트 상자에 붙여넣어요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

GitHub Enterprise로 구성 (Configure with GitHub Enterprise)

마찬가지로 GitHub Enterprise Server 또는 GitHub Enterprise Cloud에 Personal Access Token이나 GitHub App으로 연결할 수 있어요. 필요한 권한에 대한 자세한 내용은 GitHub로 구성을 참고해요.

GitHub Personal Access Token으로 연결

다음 필드를 입력해요:

  1. GitHub 저장소의 Repository URL을 텍스트 상자에 붙여넣어요.
  2. Personal Access Token을 붙여넣어요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

GitHub App으로 연결

GitHub Enterprise용 Git Sync를 구성하고 GitHub App으로 인증하려면:

  • 이미 연결된 GitHub App이 있다면 Choose an existing app 선택 → 드롭다운 메뉴에서 사용할 연결 선택 → GitHub 저장소의 Repository URL 붙여넣기.
  • 새 GitHub App으로 연결하려면 Connect to a new app 선택 → 사용할 GitHub App의 ID, GitHub Installation ID, Private Key, GitHub Enterprise 인스턴스 URL을 입력해요. GitHub Enterprise Cloud는 https://<enterprise-slug>.ghe.com처럼 생겼고, GitHub Enterprise Server는 사용자 지정 URL이에요. 그리고 GitHub 저장소의 Repository URL을 붙여넣어요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

GitLab으로 구성 (Configure with GitLab)

GitLab용 Git Sync를 구성하려면 GitLab Personal Access Token이 필요해요. 만들려면 GitLab에 로그인한 후 다음 권한으로 토큰을 만들어요:

  • Repository: 읽기·쓰기 권한
  • User: 읽기 전용 권한
  • API: 읽기·쓰기 권한

**서비스 계정(service account)**의 토큰을 사용한다면 인증 문제를 피하기 위해 서비스 계정을 GitLab 프로젝트의 멤버로 추가해요.

토큰을 만든 후 Grafana로 돌아와 다음 필드를 입력해요:

  1. Project Access Token 텍스트 상자에 토큰을 붙여넣어요.
  2. GitLab 저장소의 Repository URL을 텍스트 상자에 붙여넣어요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

Bitbucket으로 구성 (Configure with Bitbucket)

Bitbucket용 Git Sync를 구성하려면 스코프가 있는 Bitbucket API 토큰이 필요해요. 만들려면 Bitbucket에 로그인한 후 다음 권한으로 API 토큰을 만들어요:

  • Repositories: 읽기·쓰기 권한
  • Pull requests: 읽기·쓰기 권한
  • Webhooks: 읽기·쓰기·삭제 권한

Grafana로 돌아와 다음 필드를 입력해요:

  1. API Token 텍스트 상자에 토큰을 붙여넣어요.
  2. Bitbucket 저장소의 Repository URL을 텍스트 상자에 붙여넣어요. 저장소를 볼 때 브라우저 주소 표시줄에 나타나는 URL이 아니라 저장소의 Git clone URL을 사용해요. 찾으려면 Bitbucket에서 Clone을 선택하고 HTTPS URL을 복사해요. clone URL은 .git으로 끝나며, 형식은 Bitbucket 배포 방식에 따라 달라요:
  • Bitbucket Cloud: https://bitbucket.org/<workspace>/<repository>.git
  • Bitbucket Data Center and Server: https://<bitbucket-host>/scm/<PROJECT>/<repository>.git

Tip Grafana가 저장소에 연결할 때 ls-refs 오류를 반환하면 clone URL을 입력했는지(브라우저 URL이 아닌지) 확인해요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

Pure Git으로 구성 (Configure with Pure Git)

다른 Git provider를 사용한다면 Pure Git 옵션을 사용해 Personal Access Token으로 연결을 구성해야 해요:

  1. 동기화할 Git 저장소의 액세스 토큰이나 비밀번호를 Access Token에 붙여넣어요.
  2. Username을 입력해요. Git Sync는 이 이름으로 Git 저장소에 접근해요.
  3. Git 저장소의 Repository URL을 텍스트 상자에 붙여넣어요.

프로비저닝 폴더를 설정하려면 Configure repository를 선택해요.

프로비저닝 저장소 구성 (Configure the provisioning repository)

연결 인증을 구성한 후에는 프로비저닝에 사용할 저장소의 세부 정보를 계속 입력해요:

  1. 프로비저닝에 사용할 Branch를 입력해요. 기본값은 main이에요.
  2. 선택적으로 대시보드가 저장된 하위 디렉터리로 Path를 추가할 수 있어요.

저장소에 대한 연결이 검증되고 설정이 계속되도록 Choose what to synchronize를 선택해요.

동기화할 내용 선택 (Choose what to synchronize)

다음으로 이전 단계에서 지정한 외부 리소스를 Grafana 인스턴스와 동기화해요. 이러한 provisioned 리소스는 인스턴스의 나머지 부분에 영향을 주지 않으면서 provisioned 폴더의 루트 또는 새 폴더에 저장할 수 있어요. 동기화를 설정하려면:

  1. 동기화된 리소스를 Grafana에서 새 폴더 또는 루트 레벨 중 어디에 저장할지 선택해요. 이 옵션에 대한 자세한 내용은 동기화 대상(Sync targets)을 참고해요. UI는 동기화할 수 있는 사용 가능한 리소스에 대한 정보를 제공해요.
  2. 저장소 연결의 Display name을 입력해요. 이 Git Sync 연결에서 동기화된 모든 리소스는 Grafana UI에서 이 이름 아래에 나타나요.
  3. 계속하려면 Synchronize with external storage를 클릭해요.
  4. 최대 10개 연결까지 이 과정을 반복할 수 있어요.

선택적으로 관리되지 않는 리소스(unmanaged resources)를 provisioned 폴더로 내보낼 수 있어요. 방법은 외부 저장소와 동기화를 참고해요. 설정을 계속하려면 Choose additional settings를 선택해요.

외부 저장소와 동기화 (Synchronize with external storage)

동기화를 진행하려면:

  1. 알려진 제한 사항을 검토해요.
  2. 실험적 체크박스인 Migrate existing resources가 보일 수 있는데, 이를 통해 관리되지 않는 대시보드를 provisioned 폴더로 마이그레이션할 수 있어요. 보이지 않는다면 Grafana에서 비프로비저닝 리소스 내보내기를 참고해 기존 리소스를 마이그레이션하는 방법을 알아보세요.
  3. Git Sync 연결을 만들려면 Begin synchronization을 클릭해요. 과정이 완료되면 동기화된 리소스의 요약을 볼 수 있어요.

마지막 구성 단계를 위해 Choose additional settings를 클릭해요.

추가 설정 선택 (Choose additional settings)

이 마지막 단계에서 Git Sync의 추가 옵션을 구성할 수 있어요. 완료하면 Finish를 클릭해 설정을 완료해요.

동기화 간격 (Sync interval)

Sync interval (seconds) 설정을 사용해 Grafana 인스턴스가 Git Sync로 관리되는 폴더에서 업데이트를 자동으로 가져올 간격을 지정해요. 기본값은 Grafana Cloud에서 300초, Grafana OSS/Enterprise에서 60초예요.

선택 옵션 (Optional settings)

다음 선택 옵션도 설정할 수 있어요:

  • Read only를 체크해 리소스가 Grafana에서 수정될 수 없도록 해요.
  • Enable pull request option when saving을 체크해 변경 사항을 저장할 때 풀 리퀘스트를 열지 선택해요. 저장소가 main 브랜치에 대한 직접 변경을 허용하지 않는다면 풀 리퀘스트가 여전히 필요할 수 있어요.
  • Enable push to configured branch를 체크해 구성된 브랜치에 직접 커밋을 허용해요.
  • Generate dashboards previews를 체크해 풀 리퀘스트용 프리뷰 링크를 만들어요. 이 옵션은 이미지 렌더링을 사용하고 공개 접근(public access)을 활성화해야 해요.

이 옵션을 결정한 후 Commit options에서 Webhooks 또는 검증된 계정(verified account)을 구성하거나, 커밋을 서명 없이 유지하려면 Save를 클릭해 계속할 수 있어요.

웹훅 옵션 (Webhook options)

Webhook options 메뉴에서 웹훅 등록에 사용되는 자동 감지 URL을 재정의할 URL을 입력할 수 있어요. 웹훅을 설정·관리할 적절한 권한이 있는지 확인해요. Disable webhook integration을 체크할 수도 있는데, 체크하면 Grafana가 웹훅 이벤트를 등록하거나 수신하지 않고 대신 간격으로 저장소를 폴링해요. Grafana 인스턴스가 공개 인터넷에서 접근할 수 없을 때 이 옵션을 사용해요.

Git provider는 저장소에서 허용하는 웹훅 수를 제한해요. 자세한 내용과 이 제한에 도달했을 때 진행하는 방법은 웹훅 제한(Webhook limits)을 참고해요.

서명 커밋 옵션 (Signed commit options)

Grafana 13.1.0부터 **검증된 계정(verified account)**을 서명 키와 함께 구성할 수 있어요. 이를 통해 사용자가 커밋에 서명하도록 강제해 Git provider가 해당 커밋을 Verified로 표시할 수 있어요. Git Sync는 GPG, SSH, S/MIME 키를 지원해요.

Grafana 13.2.0부터 기본적으로 모든 커밋은 로그인된 Grafana 사용자를 커밋 작성자(author)로 사용해요. 자세한 내용은 작성 옵션(Authoring options)을 참고해요. 현재 Git Sync는 다음을 지원하지 않아요:

  • 암호(passphrase)로 보호된 키.
  • 개별 계정의 검증.

이 옵션을 설정하려면 UI 마법사를 따라 필요한 필드를 입력하고, 자세한 내용은 아래 섹션을 참고해요.

사전 요구 사항 (Pre-requirements)

서명 커밋을 구현하려면 Git provider에 특정 검증 계정을 설정했는지 확인해요. 검증을 설정하려면 계정의 서명 키, 이름, 이메일이 필요해요.

Git 인증용 키 생성 방법에 대한 자세한 내용은 공식 문서를 참고해요:

예: SSH 키로 커밋 서명하기 (Example: Sign your commits with an SSH key)

SSH 키를 사용해 서명 커밋을 강제하려면 다음 단계를 따라요:

  1. Commit options (advanced) 메뉴를 열어요.
  2. Commit signing에서 SSH를 선택해요.
  3. 다음 필드를 입력해요: 검증할 계정의 private key, Git provider에 표시될 서명자 name, 서명 키의 것과 일치해야 하는 서명자 e-mail address.
  4. Save를 클릭해요.

키 구성을 완료하면 사용자가 provisioned 폴더에 만드는 모든 커밋이 Verified로 표시돼요.

작성 옵션 (Authoring options)

Grafana 13.2.0부터 커밋에 **작성 정보(authoring information)**를 포함할 수 있어요.

서명되지 않은 커밋의 작성 (Authoring in unsigned commits)

커밋 서명을 활성화하지 않는다면:

  • 작성자 재정의(author override)를 추가하면 모든 커밋의 author는 구성된 재정의 값이 돼요.
  • 작성자 재정의를 선택하지 않으면 로그인된 Grafana 사용자 이름과 이메일이 커밋 작성자로 사용돼요.

서명된 커밋의 작성 (Authoring in signed commits)

커밋 서명을 활성화한다면:

  • 서명자를 커밋 작성자로 활성화하면 Git Sync는 모든 커밋의 작성자로 서명자 이름과 이메일을 사용해요.
  • 서명자를 커밋 작성자로 활성화하지 않으면 로그인된 Grafana 사용자 이름과 이메일이 커밋 author로, 구성된 서명자가 committer로 사용돼요.

Grafana에서 대시보드 확인 (Check your dashboards in Grafana)

동기화된 대시보드가 지정한 위치에서 사용 가능한지 확인해요:

  1. Dashboards로 가요.
  2. Name 열에서 대시보드 이름을 찾아요.

이제 리소스가 동기화되었으므로 이름을 사용자 지정하고, 브랜치를 변경하고, 풀 리퀘스트(PR)를 만들 수 있어요. 자세한 내용은 Git Sync로 provisioned 저장소 관리를 참고해요.

동기화된 리소스 업데이트 또는 삭제 (Update or delete your synced resources)

설정을 완료한 후 저장소 구성을 업데이트하거나 삭제하려면:

  1. Grafana Admin 플래그가 설정된 계정으로 Grafana 서버에 로그인해요.
  2. Administration > General > Provisioning을 선택해요.
  3. Repositories 탭으로 가서 수정할 저장소를 찾아요.
  4. Configure repository 화면에 접근하려면 Settings를 선택해요:
  • 구성을 수정하려면 설정 중 하나를 업데이트하고 Save를 선택해요.
  • 저장소를 삭제하려면 Delete를 클릭해요. 동기화된 리소스를 유지하거나 삭제할 수 있어요.

다음 단계 (Next steps)

버전 관리를 통해 Grafana 대시보드를 관리하도록 Git Sync를 성공적으로 설정했어요. 이제 대시보드가 GitHub 저장소와 동기화되어 협업 개발과 변경 추적이 가능해졌어요. Git Sync 사용에 대해 더 배우려면 다음 문서를 참고해요:

더 알아보기