서드 파티 Git 저장소에 연결

이 문서에서는 원격 저장소를 Dataform 저장소에 연결하는 방법을 보여줍니다. 저장소를 연결한 후에는 Dataform 개발 작업공간에서 변경한 사항을 원격 Git 저장소에 푸시하고 원격 Git 저장소에서 가져올 수 있습니다.

중요: Dataform은 온프레미스 Git 호스트의 비공개 IP 주소에 직접 연결할 수 없습니다. 비공개 네트워크의 저장소에 연결하려면 Developer Connect를 사용하세요.

HTTPS 또는 SSH를 통해 원격 저장소를 연결할 수 있습니다.

다음 표에는 지원되는 Git 제공업체와 해당 저장소에 사용할 수 있는 연결 방법이 나와 있습니다.

Git 제공업체	연결 방법
Azure DevOps 서비스	SSH
Bitbucket	Developer Connect (권장), SSH
GitHub	Developer Connect (권장), SSH 또는 HTTPS
GitLab	Developer Connect (권장), SSH 또는 HTTPS

중요: HTTPS 또는 SSH를 사용하여 원격 Git 저장소를 Dataform에 연결하려면 Git 호스트에 공개 IP 주소가 있는지 확인하세요. Git 호스트가 비공개 IP 주소 (예: 10.x.x.x, 172.16.x.x-172.31.x.x 또는 192.168.x.x)로만 구성되어 있거나 방화벽 뒤에 있는 경우 Developer Connect를 사용하여 연결하는 것이 좋습니다. HTTPS 또는 SSH를 사용하여 공개 IP 주소로 보호된 원격 저장소를 연결하려면 연결을 사용 설정하기 위해 방화벽 규칙에 필요한 Dataform 이그레스 IP 주소 범위를 추가해야 합니다.

시작하기 전에

1. 조직 또는 프로젝트에서 dataform.restrictGitRemotes 조직 정책을 사용하여 원격 Git 저장소를 제한하는 경우 원격 저장소에 연결하려는 Dataform 저장소를 만들기 전에 정책의 허용 목록에 원격 Git 저장소가 추가되었는지 확인합니다. 자세한 내용은 원격 저장소 제한을 참고하세요.

2. Dataform 저장소를 만들거나 선택합니다. 나중에 기본 Dataform 서비스 에이전트와 보안 비밀을 공유할 때 저장소가 필요합니다.

   참고: Dataform 저장소 목록에는 Dataform 워크플로 개발을 위해 생성된 저장소만 포함됩니다. 노트북이나 저장된 쿼리와 같은 BigQuery Studio 애셋의 저장소는 별도로 관리되며 이 목록에 표시되지 않습니다.

3. Git 제공업체에 필요한 권한이 있고 Dataform 저장소가 지원되는 지역에 있는지 확인합니다.

4. Developer Connect API를 사용 설정합니다.

5. Developer Connect를 Bitbucket 저장소에 연결하는 경우 Dataform이 변경사항을 푸시할 수 있도록 승인자 액세스 토큰에 저장소에 대한 쓰기 액세스 권한이 있는지 확인합니다. 자세한 내용은 액세스 토큰 만들기를 참고하세요.

필요한 역할

Dataform 저장소를 원격 Git 저장소에 연결하는 데 필요한 권한을 얻으려면 관리자에게 저장소에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• Dataform 관리자 (roles/dataform.admin)
• Developer Connect 관리자 (roles/developerconnect.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Developer Connect를 사용하여 원격 저장소를 연결하려면 기본 Dataform 서비스 에이전트에 Developer Connect 토큰 액세스 권한(roles/developerconnect.tokenAccessor) 및 Developer Connect Git 프록시 사용자(roles/developerconnect.gitProxyUser) 역할을 부여합니다. 기본 Dataform 서비스 에이전트 ID의 형식은 다음과 같습니다.

[e-mail]

Developer Connect를 사용하여 원격 저장소 연결

Developer Connect는 수동 비밀 관리의 필요성을 없애는 안내 인터페이스를 제공하여 외부 Git 제공업체와 Dataform 저장소의 통합을 간소화합니다.

Developer Connect를 사용하면 온프레미스 환경이나 가상 프라이빗 클라우드 (VPC)와 같은 비공개 호스팅 네트워크의 원격 저장소에 공개 인터넷에 노출하지 않고 연결할 수 있습니다.

중요: 비공개 네트워크의 Git 저장소에 연결하려면 Developer Connect 프록시가 필요합니다.Google Cloud 콘솔에서 새 연결을 만들면 프록시가 기본적으로 사용 설정됩니다. 공개적으로 액세스 가능한 Git 저장소에 연결하는 경우 프록시는 기본적으로 사용 설정되어 있지만 선택적으로 사용 중지할 수 있습니다. gcloud CLI 또는 Developer Connect API로 만든 기존 연결을 사용하는 경우 비공개 네트워크의 저장소에 액세스해야 한다면 프록시가 사용 설정되어 있는지 확인하세요.

참고: Dataform 저장소와 Developer Connect 연결이 서로 다른 리전에 있는 경우 Developer Connect 프록시가 사용 설정되면 리전 간 데이터 전송 비용이 추가로 발생할 수 있습니다. 자세한 내용은 Developer Connect 가격 책정을 참고하세요.

비공개 네트워크 연결 준비

비공개 네트워크의 원격 저장소에 연결하는 경우 설정을 시작하기 전에 다음 정보와 리소스를 준비해야 합니다.

• 내부 Git 호스트를 가리키는 서비스 디렉터리 서비스의 네임스페이스 및 서비스 이름입니다.
• 호스트가 비공개 또는 자체 서명 인증 기관을 사용하는 경우 PEM 형식의 인증 기관 인증서 (최대 크기 10KB)
• Git 호스트의 SSL 인증서에 호스트 URI와 일치하는 주체 대체 이름 (SAN)이 포함되어 있는지 확인합니다.

비공개로 호스팅된 네트워크의 연결 구성에 대한 자세한 내용은 다음을 참고하세요.

• Developer Connect 프록시 구성 및 사용
• 비공개 네트워크의 GitHub Enterprise에 연결
• 비공개 네트워크의 GitLab Enterprise 저장소에 연결
• 비공개 네트워크에서 호스팅되는 Bitbucket 데이터 센터 저장소에 연결

새 Developer Connect 연결 만들기

원격 저장소를 새 Developer Connect 연결에 연결하려면 다음 옵션 중 하나를 선택하세요.

Bitbucket

1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

2. 저장소를 선택합니다.

3. 설정으로 이동한 다음 Git과 연결을 클릭합니다.

4. 원격 저장소 링크 창의 원격 Git 저장소 프로토콜 섹션에서 Developer Connect를 선택합니다.

5. 저장소 선택 메뉴에서 새 저장소 연결을 클릭합니다.

6. Developer Connect를 통해 Git 저장소 연결 창에서 새 연결 만들기를 선택합니다.

7. Bitbucket을 제공업체로 선택합니다.

8. 연결 리전과 연결 이름을 지정합니다.

9. 작업공간 이름, 승인자 액세스 토큰, 읽기 액세스 토큰을 제공합니다.

10. 계속을 클릭한 다음 연결할 원격 저장소를 선택하고 연결을 클릭합니다.

11. Dataform에서 원격 저장소와 기본 브랜치를 선택합니다.

12. 설정을 완료하려면 연결을 클릭합니다.

GitHub

1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

2. 저장소를 선택합니다.

3. 설정으로 이동한 다음 Git과 연결을 클릭합니다.

4. 원격 저장소 링크 창의 원격 Git 저장소 프로토콜 섹션에서 Developer Connect를 선택합니다.

5. 저장소 선택 메뉴에서 새 저장소 연결을 클릭합니다.

6. Developer Connect를 통해 Git 저장소 연결 창에서 새 연결 만들기를 선택합니다.

7. GitHub를 제공업체로 선택합니다.

8. 연결 리전과 연결 이름을 지정합니다.

9. OAuth 인증 흐름을 트리거하려면 계속을 클릭한 후 다음 단계를 따르세요.

   1. 이해했으며 계속합니다를 클릭합니다.
   2. 다른 GitHub 계정에 GitHub 앱 설치를 선택하고 메시지에 따라 GitHub 계정 및 특정 저장소에 대한 액세스를 승인합니다.
   3. Dataform GitHub 애플리케이션을 설치할 계정을 선택합니다.
   4. 저장소 액세스 섹션에서 모든 저장소에 액세스 권한을 부여할지 아니면 일부 저장소에만 액세스 권한을 부여할지 선택합니다.
   5. 저장을 클릭합니다.

10. 연결할 원격 저장소를 선택하고 연결을 클릭합니다.

11. Dataform에서 원격 저장소와 기본 브랜치를 선택합니다.

12. 설정을 완료하려면 연결을 클릭합니다.

GitLab

1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

2. 저장소를 선택합니다.

3. 설정으로 이동한 다음 Git과 연결을 클릭합니다.

4. 원격 저장소 링크 창의 원격 Git 저장소 프로토콜 섹션에서 Developer Connect를 선택합니다.

5. 저장소 선택 메뉴에서 새 저장소 연결을 클릭합니다.

6. Developer Connect를 통해 Git 저장소 연결 창에서 새 연결 만들기를 선택합니다.

7. GitLab을 제공업체로 선택합니다.

8. 연결 리전과 연결 이름을 지정합니다.

9. API 액세스 토큰과 API 읽기 액세스 토큰을 제공합니다. 이 작업을 수행하는 방법은 액세스 토큰 만들기를 참고하세요.

10. 계속을 클릭한 다음 연결할 원격 저장소를 선택하고 연결을 클릭합니다.

11. Dataform에서 원격 저장소와 기본 브랜치를 선택합니다.

12. 설정을 완료하려면 연결을 클릭합니다.

기존 Developer Connect 연결 사용

원격 저장소를 기존 Developer Connect 연결에 연결하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

2. 저장소를 선택합니다.

3. 설정으로 이동한 다음 Git과 연결을 클릭합니다.

4. 원격 저장소 링크 창의 원격 Git 저장소 프로토콜 섹션에서 Developer Connect를 선택합니다.

5. 저장소 선택 메뉴에서 기존 Developer Connect 연결에 속하는 저장소를 선택합니다.

6. Dataform에서 원격 저장소와 기본 브랜치를 선택합니다.

7. 설정을 완료하려면 연결을 클릭합니다.

SSH를 통해 원격 저장소 연결

SSH를 통해 원격 저장소를 연결하려면 SSH 키와 Secret Manager 보안 비밀을 생성해야 합니다. SSH 키는 공개 SSH 키와 비공개 SSH 키로 구성됩니다. 공개 SSH 키를 Git 프로바이더와 공유하고 비공개 SSH 키로 Secret Manager 보안 비밀을 만들어야 합니다. 그런 다음 기본 Dataform 서비스 에이전트와 보안 비밀을 공유합니다.

Dataform은 비공개 SSH 키가 포함된 보안 비밀을 사용하여 Git 제공업체에 로그인하여 개발자 대신 변경사항을 커밋합니다. Dataform은 개발자의 Google Cloud 이메일 주소를 사용하여 이러한 커밋을 만들어 각 커밋을 알 수 있습니다.

경고: 비공개 SSH 키는 해당 서비스 에이전트 또는 서비스 계정을 사용하는 모든 Dataform 사용자와 공유됩니다. Git 제공업체에서 머신 사용자를 만들고 Dataform에서 사용할 원격 Git 저장소에 대한 액세스를 제한하는 것이 좋습니다. Google Cloud 프로젝트 소유자 및 Dataform 관리자 역할이 있는 Dataform 사용자만 키를 사용하여 저장소를 연결할 수 있습니다. Dataform 사용자는 키 자체를 볼 수 없습니다.

SSH를 통해 원격 저장소를 Dataform 저장소에 연결하려면 다음 단계를 따르세요.

1. Git 제공업체에서 다음 중 하나를 수행합니다.

   Azure DevOps 서비스

   1. Azure DevOps 서비스에서 비공개 SSH 키를 만듭니다.
   2. Azure DevOps 서비스 저장소에 공개 SSH 키를 업로드합니다.

   Bitbucket

   1. Bitbucket에서 비공개 SSH 키를 만듭니다.
   2. Bitbucket 저장소에 공개 SSH 키를 업로드합니다.

   GitHub

   1. GitHub에서 비공개 SSH 키를 만듭니다.
   2. GitHub 공개 SSH 키를 GitHub 저장소에 업로드합니다.

   GitLab

   1. GitLab에서 비공개 SSH 키를 만듭니다.
   2. GitLab 저장소에 GitLab 공개 SSH 키를 업로드합니다.

2. Secret Manager에서 보안 비밀을 만들고 비공개 SSH 키를 보안 비밀 값으로 설정합니다.

   1. 기본 Dataform 서비스 에이전트에 보안 비밀에 대한 액세스 권한을 부여합니다.

      기본 Dataform 서비스 에이전트의 형식은 다음과 같습니다.

      [e-mail]
      

   2. 서비스 에이전트 또는 서비스 계정에 roles/secretmanager.secretAccessor 역할을 부여합니다.

3. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

4. 원격 저장소에 연결할 Dataform 저장소를 선택합니다.

5. 저장소 페이지에서 설정 > Git과 연결을 클릭합니다.

6. 원격 저장소 링크 창의원격 Git 저장소 URL 필드에 .git로 끝나는 원격 Git 저장소 URL을 입력합니다.

   원격 Git 저장소의 URL은 다음 형식 중 하나여야 합니다.

   • 절대 URL: ssh://git@{host_name}[:{port}]/{repository_path}. port는 선택사항입니다.
   • SCP와 같은 URL: git@{host_name}:{repository_path}

7. 기본 원격 브랜치 이름 필드에 원격 Git 저장소의 기본 개발 브랜치 이름을 입력합니다.

8. 보안 비밀 드롭다운에서 원격 Git 저장소 보안 비밀을 선택합니다.

9. SSH 공개 호스트 키 값 필드에 Git 제공업체의 공개 호스트 키를 입력합니다.

   Azure DevOps 서비스

   1. Azure DevOps Services 공개 호스트 키를 검색하려면 터미널에서 다음 명령어를 실행합니다.

      ssh-keyscan -t rsa ssh.dev.azure.com
      

   2. 출력된 키 중 하나를 복사합니다. 이때 줄 시작 부분의 ssh.dev.azure.com는 생략합니다. 복사하는 값은 다음 형식이어야 합니다.

      ALGORITHM BASE64_KEY_VALUE
      

      예를 들면 다음과 같습니다.

      ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
      

      이 키가 Azure DevOps Services에서 최신 상태인지 확인합니다.

   Bitbucket

   1. Bitbucket 공개 호스트 키를 검색하려면 터미널에서 다음 명령어를 실행합니다.

      curl https://bitbucket.org/site/ssh
      

   2. 이 명령어는 공개 호스트 키 목록을 반환합니다. 목록에서 키 중 하나를 선택하고 줄 시작 부분의 bitbucket.org를 생략한 후 복사합니다. 복사하는 값은 다음 형식이어야 합니다.

      ALGORITHM BASE64_KEY_VALUE
      

      예를 들면 다음과 같습니다.

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
      

      이 키가 Bitbucket에서 최신 상태인지 확인합니다.

   GitHub

   1. GitHub 공개 호스트 키를 가져오려면 GitHub의 SSH 키 지문을 참고하세요.

   2. 페이지에는 공개 호스트 키 목록이 포함되어 있습니다. 이 중 하나를 선택하고 줄의 시작 부분에서 github.com를 생략하여 복사합니다. 복사하는 값은 다음 형식이어야 합니다.

      ALGORITHM BASE64_KEY_VALUE
      

      예를 들면 다음과 같습니다.

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
      

      이 키가 GitHub에서 최신 상태인지 확인합니다.

   GitLab

   1. GitLab 공개 호스트 키를 가져오려면 SSH known_hosts 항목을 참고하세요.

   2. 페이지에는 공개 호스트 키 목록이 포함되어 있습니다. 이 중 하나를 선택하고 줄의 시작 부분에서 gitlab.com를 생략하여 복사합니다. 복사하는 값은 다음 형식이어야 합니다.

      ALGORITHM BASE64_KEY_VALUE
      

      예를 들면 다음과 같습니다.

      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
      

      이 키가 GitLab에서 최신 상태인지 확인합니다.

10. 링크를 클릭합니다.

HTTPS를 통해 원격 저장소 연결

HTTPS를 통해 원격 저장소를 연결하려면 개인 액세스 토큰으로 Secret Manager 보안 비밀을 만들고 기본 Dataform 서비스 에이전트와 보안 비밀을 공유해야 합니다.

그러면 Dataform이 액세스 토큰을 사용하여 Git 제공업체에 로그인하여 개발자 대신 변경사항을 커밋합니다. Dataform은 개발자의 Google Cloud 이메일 주소를 사용하여 이러한 커밋을 만들어 각 커밋을 알 수 있습니다.

경고: 액세스 토큰은 해당 서비스 에이전트 또는 서비스 계정을 사용하는 모든 Dataform 사용자 간에 공유됩니다. Git 제공업체에서 머신 사용자를 만들고 Dataform에서 사용할 원격 Git 저장소에 대한 액세스를 제한하는 것이 좋습니다. Google Cloud 프로젝트 소유자 및 Dataform 관리자 역할이 있는 Dataform 사용자만 토큰을 사용하여 저장소를 연결할 수 있습니다. Dataform 사용자는 토큰 자체를 볼 수 없습니다.

HTTPS를 통해 원격 저장소를 Dataform 저장소에 연결하려면 다음 단계를 따르세요.

1. Git 제공업체에서 다음을 수행합니다.

   GitHub

   1. GitHub에서 세분화된 개인 액세스 토큰 또는 기본 개인 액세스 토큰을 만듭니다.

      • 세분화된 GitHub 개인 액세스 토큰의 경우 다음을 실행합니다.

      1. 저장소 액세스를 선택한 저장소만으로 선택한 다음 연결할 저장소를 선택합니다.

      2. 저장소 콘텐츠에 대한 읽기 및 쓰기 액세스 권한을 부여합니다.

      3. 필요에 따라 토큰 만료 시간을 설정합니다.

      • 기본 GitHub 개인 액세스 토큰의 경우 다음을 실행합니다.

      1. Dataform에 repo 권한을 부여합니다.

      2. 필요에 따라 토큰 만료 시간을 설정합니다.

   2. 조직에서 SAML 싱글 사인온(SSO)을 사용하는 경우 토큰을 승인합니다.

   GitLab

   1. GitLab에서 GitLab 개인 액세스 토큰을 만듭니다.

   2. 토큰 이름을 dataform으로 지정합니다.

      GitLab 개인 액세스 토큰의 이름은 dataform이어야 합니다.

   3. Dataform에 api, read_repository, write_repository 권한을 부여합니다.

   4. 필요에 따라 토큰 만료 시간을 설정합니다.

2. Secret Manager에서 원격 저장소의 개인 액세스 토큰이 포함된 보안 비밀을 만듭니다.

3. 기본 Dataform 서비스 에이전트에 보안 비밀에 대한 액세스 권한을 부여합니다.

   기본 Dataform 서비스 에이전트의 형식은 다음과 같습니다.

   [e-mail]
   

   1. 서비스 에이전트에 roles/secretmanager.secretAccessor 역할을 부여합니다.

4. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

5. 원격 저장소에 연결할 Dataform 저장소를 선택합니다.

6. 저장소 페이지에서 설정 > Git과 연결을 클릭합니다.

7. 원격 저장소 링크 창의원격 Git 저장소 URL 필드에 .git로 끝나는 원격 Git 저장소 URL을 입력합니다.

   원격 Git 저장소의 URL에 사용자 이름이나 비밀번호가 포함될 수 없습니다.

8. 기본 원격 브랜치 이름 필드에 원격 Git 저장소의 기본 개발 브랜치 이름을 입력합니다.

9. 보안 비밀 드롭다운에서 원격 Git 저장소 보안 비밀을 선택합니다.

10. 링크를 클릭합니다.

원격 저장소 연결 수정

Dataform 저장소와 원격 Git 저장소 간의 연결을 수정하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

2. 수정하려는 저장소를 클릭합니다.

3. 저장소 페이지에서 설정 > Git 연결 수정을 클릭합니다.

4. 원격 저장소에 연결 창에서 연결 설정을 수정합니다.

5. 업데이트를 클릭합니다.

다음 단계

• Dataform 저장소에 대해 자세히 알아보려면 저장소 만들기를 참고하세요.

• 개발 작업공간을 만들려면 작업공간 만들기 참조하기

• 원격 저장소 연결 문제를 해결하는 방법은 Dataform 문제 해결을 참조하세요.