콘텐츠로 이동

코드 호스트 연결

Control Center는 앱 전반에서 forge라고 부르는 세 가지 코드 호스트, 즉 GitHub, GitLab, Bitbucket Cloud와 함께 작동합니다. 이 중 기본값은 없습니다. 하나를 연결하면 모든 것이 작동하고, 여러 개를 연결하면 하나의 워크스페이스가 세 곳의 저장소를 동시에 담을 수 있습니다.

forge는 등록할 때 origin 리모트에서 읽어 들이는, 각 저장소의 속성입니다. 직접 고르는 일이 없으며, 잘못 설정할 만한 워크스페이스별 설정도 없습니다.

  1. 설정 → 나 → 프로필(/settings/you/profile)을 엽니다.
  2. 코드 호스팅 카드를 찾습니다. 연결 여부와 상관없이 지원되는 모든 forge가 나열됩니다.
  3. GitHub에서는 GitHub에 로그인을 누릅니다. GitLab이나 Bitbucket에서는 토큰 추가를 눌러 토큰을 붙여넣습니다.

GitHub는 로그인 방식만 지원합니다. 로그인은 서버 소유자가 설정한 서버 자체 GitHub App이나 Control Center Connect를 거치거나, 설정 → 워크스페이스 → 연동에서 워크스페이스 관리자가 이 워크스페이스에 대해 고른 앱을 거쳐 진행됩니다(GitHub 통합 설정 참고). 붙여 넣을 GitHub 토큰은 없습니다. GitLab과 Bitbucket은 여전히 개인 토큰을 사용합니다.

어느 방식이든 자격 증명은 본인의 것이며 서버에 저장되고 사용자 id를 키로 삼습니다. 토큰을 입력한 머신에는 아무것도 저장되지 않고, 로그인하는 모든 기기가 같은 자격 증명을 사용하며, 다른 멤버는 이를 읽을 수 없습니다. 효력은 다음 요청부터 발생합니다. 재시작할 것은 없고, 연결을 해제하면 즉시 전송이 중단됩니다.

카드에 자격 증명이 어디에서 사용되는지 표시됩니다. GitLab 또는 Bitbucket 토큰은 서버의 모든 워크스페이스에서 본인의 것이므로 한 번만 붙여 넣으면 됩니다. GitHub 로그인도 마찬가지입니다. 단, 워크스페이스에 자체 로그인 앱이 있으면 예외입니다. 그 워크스페이스는 고유의 GitHub 로그인을 유지하며, 카드에 그 사실이 표시됩니다.

각 행에는 본인의 자격 증명 상태가 표시됩니다. 본인의 자격 증명만 본인을 대신해 응답하며, 다른 것이 대신하지 않습니다:

행에 표시되는 내용 의미
octocat(으)로 로그인했습니다 본인의 자격 증명이 사용되고 있습니다
연결되지 않음 이 forge에 대한 자격 증명이 없습니다
octocat(으)로 된 GitHub 로그인이 만료되었습니다. 다시 로그인하세요. forge에서 로그인이 만료되었거나 취소되었습니다
일시 중지됨: 이 워크스페이스의 로그인 서비스가 변경되었습니다 이 워크스페이스가 다른 로그인 서비스로 전환되었습니다. 로그인은 유지되며, 다시 전환하면 작동합니다. 그래서 로그인 버튼이 없습니다
지금은 GitHub에 연결할 수 없습니다. 다시 시도하는 중입니다. 일시적 장애입니다. Control Center가 계속 재시도하므로 할 일은 없습니다
로그인을 사용할 수 없는 이유를 설명하는 문장 예: 이 워크스페이스에는 GitHub 로그인이 설정되어 있지 않습니다. 또는 이 워크스페이스의 로그인 서비스 신원이 변경되었습니다. 관리자가 확인해야 합니다. 관리자에게는 문제를 해결하는 설정으로 가는 버튼이 표시됩니다
Forge 토큰 생성 위치
GitLab api 권한이 있는 개인 액세스 토큰 gitlab.com → User settings → Access tokens
Bitbucket Atlassian API 토큰과 계정 이메일 id.atlassian.com → Security → API tokens

Bitbucket은 계정 이메일을 사용자 이름으로, API 토큰을 비밀번호로 사용해 인증하므로, Bitbucket 대화 상자에서 둘 다 입력합니다. Bitbucket 저장소, 프로젝트 또는 워크스페이스 액세스 토큰은 어떤 개인에게도 속하지 않으므로 이 대화 상자는 그런 토큰을 거부합니다. 대신 자동화 토큰입니다. GitLab의 프로젝트 또는 그룹 액세스 토큰도 마찬가지입니다. GitLab은 저장하기 전에 그 토큰이 누구의 것인지 확인하며, 봇 토큰은 여기서 거부됩니다.

토큰은 결코 한 워크스페이스에 묶이지 않습니다. forge마다 하나를 보유하며, 서버의 모든 워크스페이스가 그것을 사용합니다. 연결 해제는 모든 워크스페이스에서 그 토큰을 제거합니다.

사람이 뒤에 없는 작업(에이전트 실행, 파이프라인, PR 폴링)에도 자격 증명이 필요하며, forge마다 답하는 방식이 다릅니다:

  • GitHub — 한 번에 저장소 하나에 대한 토큰. 서버의 GitHub App에서 또는 Connect를 통해 발급되며, 책임지는 멤버가 그곳에서 할 수 있는 범위로 제한됩니다. 사람의 로그인을 통째로 넘기는 일은 결코 없으며, 환경 변수나 붙여 넣은 토큰이 대신하지도 않습니다. GitHub 통합 설정을 참고하십시오
  • GitLab과 Bitbucket — 저장소의 자동화 토큰만 사용합니다. 워크스페이스 관리자가 그 저장소에 대해, 또는 워크스페이스에서 해당 forge의 모든 저장소에 대해 추가한 봇 액세스 토큰입니다. 저장소 자체의 토큰이 워크스페이스 토큰보다 우선합니다. 풀 리퀘스트 폴링, AI 리뷰 댓글, 누구도 요청하지 않은 푸시와 머지 리퀘스트는 모두 이 토큰을 사용하므로, forge에서는 멤버가 아니라 그 봇으로 표시됩니다. 멤버의 개인 토큰이 대신하지 않으며, 서버 전역 토큰이나 환경 변수 토큰도 없습니다. 토큰이 없으면 해당 저장소의 백그라운드 작업은 일시 중지되고, 저장소 액세스 알림이 이를 알려 줍니다.

본인이 요청한 작업(댓글, 리뷰, 본인을 위해 연 에이전트의 머지 리퀘스트)은 여전히 본인의 토큰을 사용합니다.

워크스페이스 관리자만 자동화 토큰을 보거나 변경할 수 있습니다. 각 토큰은 저장할 때 forge에서 확인합니다. 사람으로 행동하는 토큰(GitLab 개인 액세스 토큰, Atlassian API 토큰, 또는 누군가의 계정으로 로그인하는 모든 Bitbucket 토큰)은 거부되며, 대상 저장소를 읽을 수 없는 토큰도 거부됩니다.

  • 저장소 하나에 대해: 설정 → 워크스페이스 → 리포지토리를 엽니다. 자동화 토큰 카드에 GitLab과 Bitbucket 저장소마다 거기서 작동하는 봇이 나열되며, 워크스페이스 토큰 사용 또는 **토큰이 없습니다. 이곳의 자동화가 일시 중지되었습니다.**로 표시됩니다. 저장소의 행에서 토큰 추가를 누릅니다.
  • forge의 모든 저장소에 대해: 설정 → 워크스페이스 → 연동을 열고, 자동화 토큰 카드에서 GitLab 또는 Bitbucket 행의 토큰 추가를 누릅니다. 저장 후에는 토큰이 읽을 수 없는 저장소의 이름이 표시되며, 그 저장소는 일시 중지된 상태로 남습니다.

백그라운드 작업이 이미 일시 중지되어 있으면, 관리자에게는 저장소 액세스 알림에도 토큰 추가가 바로 표시됩니다. 토큰 업데이트는 토큰을 교체하고, 휴지통 버튼은 토큰을 제거하며, 토큰이 없어진 저장소는 일시 중지됩니다. forge가 저장된 토큰을 나중에 거부하면(취소되었거나 만료됨) 해당 행에 그렇다고 표시되며, 그 토큰이 담당하던 저장소는 토큰을 교체할 때까지 일시 중지됩니다.

Forge 자동화 토큰 생성 위치
GitLab read_api 및 read_repository 권한이 있는 프로젝트 또는 그룹 액세스 토큰. 댓글, 머지 리퀘스트, 푸시를 위해서는 api와 write_repository를 추가 프로젝트 또는 그룹 → 설정 → 액세스 토큰
Bitbucket 저장소 읽기 권한이 있는 저장소, 프로젝트 또는 워크스페이스 액세스 토큰. 댓글과 풀 리퀘스트를 위해서는 풀 리퀘스트 쓰기 권한을, 푸시를 위해서는 저장소 쓰기 권한을 추가 저장소, 프로젝트 또는 워크스페이스 → 설정 → 액세스 토큰

GitLab은 작업을 토큰의 봇 사용자로 표시하고, Bitbucket은 액세스 토큰의 이름으로 표시합니다.

Bitbucket: 액세스 토큰인가 API 토큰인가

섹션 제목: “Bitbucket: 액세스 토큰인가 API 토큰인가”

Bitbucket에는 두 종류의 토큰이 있으며, Control Center는 이를 구분합니다:

  • API 토큰(id.atlassian.com)은 본인의 Atlassian 계정에 속하며 이메일과 함께 사용합니다. 본인의 자격 증명이므로 설정 → 나 → 프로필의 코드 호스팅 아래에 넣습니다.
  • 액세스 토큰(저장소, 프로젝트 또는 워크스페이스 설정에서 생성)은 사람이 아니라 그 저장소, 프로젝트 또는 워크스페이스에 속합니다. 자동화 토큰이므로 자동화 토큰 아래에 넣습니다.

각 대화 상자는 다른 종류의 토큰을 거부하고, 어디에 넣어야 하는지 알려 줍니다.

같은 사람이 GitHub에서는 octocat이지만 GitLab에서는 전혀 다른 이름입니다. Control Center는 forge별로 아이덴티티를 해석해 저장소마다 올바른 것을 사용합니다. 덕분에 여러 forge가 섞인 워크스페이스에서도 “내 리뷰 필요”, “내가 생성”, “내가 승인”이 정확해집니다.

어떤 forge의 아이덴티티가 해석되지 않으면 그 저장소는 모두와 일치하는 것으로 처리되는 대신 받은편지함에 아무것도 제공하지 않습니다. 받은편지함은 모든 것을 확인했다고 주장하는 대신 그 사실을 알려 줍니다.

본인 계정으로 볼 수 있는 것만 보입니다

섹션 제목: “본인 계정으로 볼 수 있는 것만 보입니다”

저장소의 풀 리퀘스트는 워크스페이스 역할이 저장소를 허용하고 본인의 forge 계정이 그 저장소를 읽을 수 있을 때에만 나에게 보입니다. 워크스페이스 관리자와 소유자도 같은 규칙을 따릅니다. 일부 저장소가 숨겨지면, 받은편지함과 PR 큐는 저장소 이름을 언급하지 않고 그 개수와 이유를 알려 줍니다:

  • GitHub에 로그인하면 리포지토리 3개의 풀 리퀘스트를 더 볼 수 있습니다: 이 forge는 아직 여기에 연결되어 있지 않습니다. 로그인하면 표시됩니다
  • GitHub 계정에서 볼 수 없어 리포지토리 3개가 숨겨져 있습니다: forge에서 접근 권한이 있는 사람에게 문의하세요
  • 이 워크스페이스에서 접근 권한이 없어 리포지토리 3개가 숨겨져 있습니다: 워크스페이스 관리자에게 접근 권한을 요청하세요
  • 리포지토리 3개에 대한 접근 권한을 더 확인하는 중…: Control Center가 본인 계정이 읽을 수 있는 항목을 확인하는 동안 잠시 표시됩니다

코드에도 같은 규칙이 적용됩니다. 저장소의 파일, diff, 검색 또는 해당 저장소의 터미널을 열려면 이 워크스페이스에서 그 저장소에 대한 권한이 있어야 하고 본인의 forge 계정이 그 저장소를 읽을 수 있어야 합니다. 워크스페이스 관리자도 마찬가지이며, 서버 소유자만 예외입니다. forge에 도달할 수 없어 확인하지 못하면 forge 이름과 함께 “포지 접근 권한을 확인할 수 없습니다. 다시 시도하세요.“가 표시됩니다. 코드는 forge를 따릅니다를 참고하세요.

이 규칙은 그 풀 리퀘스트에서 만들어지는 모든 것에도 적용됩니다. 리뷰 스페이스, 그 메시지, 에이전트 실행은 본인이 해당 풀 리퀘스트를 볼 수 없는 동안 사라지며, 열려 있던 리뷰 스페이스는 접근 권한을 잃으면 닫힙니다. 숨겨진 풀 리퀘스트에 관한 파이프라인 실행은 실행 목록에서 빠집니다. 본인을 위해 일하는 에이전트도 그 리뷰 스페이스를 읽을 수 없습니다. 워크스페이스의 저장소 목록에는 코드 호스트 계정이 아직 접근할 수 없는 저장소를 포함해, 이 워크스페이스에서 본인이 접근할 수 있는 모든 저장소가 표시됩니다.

forge가 속도 제한을 받거나 사용할 수 없으면, Control Center는 몇 분 동안 마지막으로 확인한 내용을 계속 보여 주고, 그 뒤에는 다시 확인할 수 있을 때까지 해당 풀 리퀘스트를 숨깁니다.

받은편지함과 PR 큐는 워크스페이스에 존재하는 모든 forge로 뻗어 나가 결과를 하나의 흐름으로 병합합니다. GitHub 풀 리퀘스트와 Bitbucket 풀 리퀘스트가 공급업체별로 묶이지 않고 시간순으로 나란히 놓입니다.

장애는 격리됩니다. 중단되었거나 속도 제한에 걸린 forge는 다른 forge에 영향을 주지 않고, 해당 forge의 저장소는 복구될 때까지 마지막으로 알려진 상태를 유지합니다. 전체 받은편지함을 비우는 일은 없습니다. 서버가 더 이상 도달할 수 없는 저장소는 오래된 풀 리퀘스트를 보여 주는 대신 목록에서 빠지고, 저장소 액세스 알림이 그 저장소를 해결 방법과 함께 알려 줍니다. GitHub App을 조직에 설치하거나, 저장소를 App의 저장소에 추가하거나, 일시 중단된 설치를 재개하거나, 책임 있는 멤버가 다시 로그인하거나, GitLab 또는 Bitbucket 저장소에 자동화 토큰을 추가하면 됩니다. 관리자에게는 GitHub App 단계와 토큰 추가를 위한 버튼이 표시됩니다.

모든 forge는 핵심 흐름, 즉 풀 리퀘스트 조회와 열기, diff 읽기, 인라인 및 최상위 댓글 작성, 리뷰, 병합, 닫기를 지원합니다. 그 외에는 실제로 서로 다르며, Control Center는 조용히 실패하는 컨트롤을 보여 주는 대신 forge가 할 수 없는 것은 숨깁니다.

기능 GitHub GitLab Bitbucket
일괄(대기) 리뷰 ✓ ✓ —
변경 요청 ✓ ✓ ✓
파일별 “확인함” 상태 동기화 ✓ — —
이모지 반응 ✓ ✓ —
팀 / 그룹 리뷰어 ✓ ✓ —
리뷰어 제안 ✓ — ✓
PR의 CI 결과 ✓ ✓ ✓
CI 작업의 단계/로그 자세히 보기 ✓ ✓ —
스택형 풀 리퀘스트 ✓ — —
PR 설명 템플릿 ✓ ✓ —
알림 폴링 ✓ — —
풍부한 사용자 프로필 ✓ ✓ —
서버 측 PR head ref ✓ ✓ —

기능이 빠진 곳에서는 해당 기능이 정직하게 축소됩니다:

  • 확인함 상태는 여전히 작동하지만, 설정한 기기에서만 그렇습니다.
  • Bitbucket에서 일괄 리뷰는 댓글 하나씩 게시되므로, 리뷰어는 한꺼번에 도착하는 대신 개별적으로 도착하는 것을 봅니다.
  • Bitbucket에는 PR head ref가 없으므로, 풀 리퀘스트를 체크아웃하면 소스 브랜치를 이름으로 가져오며, 그 브랜치가 삭제되면 실패합니다.

GitLab은 풀 리퀘스트를 머지 리퀘스트라고 부릅니다. Control Center는 자체 모델 전반에서 “풀 리퀘스트”라고 하며, 해당 forge를 이야기할 때는 그 forge의 명칭을 사용합니다.

PR 목록이 비어 있으면서 forge가 연결되지 않았다고 표시됩니다

섹션 제목: “PR 목록이 비어 있으면서 forge가 연결되지 않았다고 표시됩니다”

그 forge에 대한 자격 증명이 없습니다. 설정 → 나 → 프로필 → 코드 호스팅에서 GitHub에 로그인하거나 GitLab 또는 Bitbucket 토큰을 붙여넣습니다. 다른 forge의 저장소는 영향을 받지 않습니다.

forge를 연결했는데 저장소에 여전히 아무것도 표시되지 않습니다

섹션 제목: “forge를 연결했는데 저장소에 여전히 아무것도 표시되지 않습니다”

행의 상태를 확인한 다음, PR 목록 위의 알림을 보십시오. “GitHub에 로그인하면 … 풀 리퀘스트를 더 볼 수 있습니다”는 해당 저장소에 본인 계정이 아직 연결되지 않았다는 뜻입니다. “… 본인 계정에서 볼 수 없어 숨겨져 있습니다”는 forge가 접근 권한을 주지 않았다는 뜻입니다. GitHub에서는 저장소 액세스 알림이 GitHub App이 저장소의 조직에 설치되지 않았거나 저장소를 포함하지 않을 때 이를 알려 줍니다.

백그라운드 작업이 GitLab 또는 Bitbucket 저장소에서 일시 중지되었습니다

섹션 제목: “백그라운드 작업이 GitLab 또는 Bitbucket 저장소에서 일시 중지되었습니다”

저장소에 이를 읽을 수 있는 자동화 토큰이 없습니다. 워크스페이스 관리자가 저장소 또는 워크스페이스 전체에 대해 하나를 추가해야 합니다. 자동화 토큰 추가를 참고하세요. 본인의 개인 토큰으로는 일시 중지가 해제되지 않습니다. 백그라운드 작업은 멤버의 토큰을 결코 사용하지 않습니다.

등록에는 세 가지가 모두 필요합니다. 경로가 git 워크트리 안에 있고, origin 리모트가 있으며, 그 리모트가 github.com, gitlab.com 또는 bitbucket.org를 가리켜야 합니다. origin은 또한 연결하려는 저장소 자체여야 하며, 워크스페이스 고유 저장소 밖에 있는 폴더는 서버 소유자만 연결할 수 있습니다. 워크스페이스에 저장소 추가를 참고하십시오.

권한이 있지만 저장소에서 내 계정이 읽을 수 없다고 나옵니다

섹션 제목: “권한이 있지만 저장소에서 내 계정이 읽을 수 없다고 나옵니다”

본인의 forge 계정으로는 그 저장소를 읽을 수 없으므로, 워크스페이스가 무엇을 허용하든 코드는 본인에게 닫혀 있습니다. 위의 코드 호스팅에서 forge에 로그인하거나, forge에서 해당 저장소에 대한 접근 권한을 받으세요.

“포지 접근 권한을 확인할 수 없습니다”

섹션 제목: ““포지 접근 권한을 확인할 수 없습니다””

forge에 도달할 수 없어 접근 권한을 확인하지 못했으므로, Control Center는 추측하는 대신 거부했습니다. 잠시 후 다시 시도하세요.

저장소가 이제 다른 저장소를 가리킵니다

섹션 제목: “저장소가 이제 다른 저장소를 가리킵니다”

해당 경로의 저장소가 바뀌었습니다. 삭제되었다가 다시 만들어졌거나, 이동한 뒤 대체되었습니다. 워크스페이스 관리자가 알림이나 저장소 행에서 다시 연결을 누르기 전까지 Control Center는 이 저장소로 아무것도 보내지 않습니다. 단순한 이름 변경이나 이전은 자동으로 따라가며 이 메시지가 나타나지 않습니다.

많이 사용한 뒤 한동안 모든 것이 작동을 멈춥니다

섹션 제목: “많이 사용한 뒤 한동안 모든 것이 작동을 멈춥니다”

속도 제한 서킷 브레이커입니다. 기본 한도에 도달했다고 알리는 forge가 있으면, 클라이언트는 시간 창이 지날 때까지 네트워크 호출 없이 이후 요청을 로컬에서 실패시킵니다. 따라서 재시도 폭주가 한도를 더 악화시킬 수 없습니다. 일시적 실패는 지수 백오프로 재시도합니다.