필요한 역할
Git 서비스 연결은 Super Admin만 조회, 추가, 수정, 해제할 수 있습니다. 다른 역할에는 Integrations 메뉴가 표시되지 않으며 직접 URL로도 접근할 수 없습니다.
사전 준비
- 연결할 Git 서비스의 개인용 접근 토큰(PAT) 또는 그에 해당하는 접근 토큰
- 토큰을 구분할
Integration Token Name - GitHub.com 또는 GitLab.com이 아닌 서버를 사용하는 경우 XEIZE에서 접근할 수 있는 서버 주소
연결 화면에는 Git 서비스와 관계없이 같은 api 권한 안내가 표시됩니다. 이 문구는 서비스별 공식 권한 이름이나 최소 권한을 뜻하지 않습니다. 토큰에는 아래 작업에 필요한 권한을 부여합니다.
- 토큰 유효성 확인
- 접근 가능한 조직, 그룹 또는 프로젝트 조회
- 대상 저장소 목록 조회와 소스 읽기
토큰 종류와 최소 권한은 회사의 Git 서비스 정책과 XEIZE 설치 환경에 맞게 설정합니다. 토큰 값은 문서, 채팅, 로그에 기록하지 않습니다.
서비스별 URL 설정
| 서비스 | 기본 연결 대상 | 사용자 지정 URL | 지원 환경 |
|---|---|---|---|
| GitHub | https://github.com |
선택 | GitHub.com 또는 별도로 운영하는 GitHub 서버 |
| GitLab | https://gitlab.com |
선택 | GitLab.com 또는 별도로 운영하는 GitLab 서버 |
| Bitbucket | 자동 입력 없음 | 필수 | 직접 운영하는 Bitbucket Data Center 또는 Server |
Bitbucket은 회사나 기관에서 직접 운영하는 Data Center 또는 Server만 연결할 수 있습니다. 서버 주소는 반드시 입력해야 합니다.
GitHub 연결
메뉴 경로: Integrations > GitHub > Connect
- 사이드바에서
Integrations를 선택합니다. - GitHub 카드에서
Connect를 선택합니다. Account Credential에 GitHub 접근 토큰을 입력합니다.Integration Token Name에 용도를 알아볼 수 있는 이름을 입력합니다. 예:github-production.- GitHub.com이 아닌 서버를 사용한다면
Use Custom GitHub URL을 켜고 서버 주소를 입력합니다. 예:https://github.company.com. Connect를 선택합니다.- 성공 메시지와
Current Connection에 연결 이름과 URL이 표시되는지 확인합니다.
사용자 지정 URL을 켜지 않으면 https://github.com에 연결합니다.
GitLab 연결
메뉴 경로: Integrations > GitLab > Connect
- 사이드바에서
Integrations를 선택합니다. - GitLab 카드에서
Connect를 선택합니다. Account Credential에 GitLab 접근 토큰을 입력합니다.Integration Token Name을 입력합니다. 예:gitlab-platform.- GitLab.com이 아닌 서버를 사용한다면
Use Custom GitLab URL을 켜고 서버 주소를 입력합니다. 예:https://gitlab.company.com. Connect를 선택합니다.- 성공 메시지와 연결 정보를 확인합니다.
사용자 지정 URL을 켜지 않으면 https://gitlab.com에 연결합니다.
Bitbucket 연결
메뉴 경로: Integrations > Bitbucket > Connect
- 사이드바에서
Integrations를 선택합니다. - Bitbucket 카드에서
Connect를 선택합니다. Account Credential에 Bitbucket 접근 토큰을 입력합니다.Integration Token Name을 입력합니다. 예:bitbucket-dc-production.- 필수 항목인
Bitbucket Server URL에 Data Center 또는 Server 주소를 입력합니다. 예:https://bitbucket.company.com. Connect를 선택합니다.- 성공 메시지와 연결 정보를 확인합니다.
GitHub와 GitLab의 사용자 지정 URL과 달리 Bitbucket 서버 URL은 생략할 수 없습니다.
여러 토큰 관리
한 Git 서비스에 여러 연결을 등록할 수 있습니다. 연결 화면에서는 다음 작업을 지원합니다.
- 연결 선택: 선택 목록에서 관리할 연결을 고릅니다.
Add: 같은 Git 서비스의 새 연결을 추가합니다.Update: 연결 이름, 토큰 또는 URL을 갱신합니다. 업데이트할 때는 유효한 토큰을 다시 입력해야 합니다.Disconnect: 선택한 연결을 비활성화합니다.
마지막으로 선택한 연결은 브라우저에 Git 서비스별로 저장되며, 이후 Add Project 화면에서도 먼저 선택됩니다.
연결을 해제하면 새 프로젝트를 등록할 때 해당 연결을 더 이상 선택할 수 없습니다. 해제하기 전에 이 연결을 사용하는 프로젝트가 있는지 확인합니다.
연결 문제 해결
연결 실패
- 토큰이 만료되거나 폐기되지 않았는지 확인합니다.
- 토큰이 대상 조직과 저장소를 조회할 수 있는지 확인합니다.
- 사용자 지정 URL에
https://부터 시작하는 전체 서버 주소를 입력했는지 확인합니다. - 회사에서 직접 운영하는 서버라면 XEIZE가 해당 서버에 접속할 수 있는지 확인합니다.
조직 또는 프로젝트가 보이지 않음
Update에서 토큰을 다시 등록한 뒤 연결을 확인합니다.- 토큰 소유자가 대상 조직, 그룹 또는 Bitbucket 프로젝트에 접근할 수 있는지 확인합니다.
- Git 서비스나 조직 정책에서 통합 로그인(SSO) 승인 또는 개인용 접근 토큰 사용 승인을 요구한다면 서비스 관리자에게 확인합니다.
연결은 있는데 다른 토큰이 사용됨
Connect 또는 Add Project 화면의 Integration 선택 목록에서 원하는 연결 이름을 다시 선택합니다.