Control Center Connect 레퍼런스
Control Center Connect는 자체 앱을 등록하지 않은 서버를 위해 프로바이더 로그인을
실행합니다. 서버는 Control Center의 호스팅 Connect, 조직이 운영하는 Connect(Connect
서버 실행) 중 하나를 쓰거나, 아무것도 쓰지
않습니다. 이 선택은 설정 → 서버 → 싱글 사인온 → Control Center Connect,
cc_server connect, 또는 CC_CONNECT_URL에서 합니다. 워크스페이스는 관리자가 설정 → 워크스페이스 → 연동에서 그 워크스페이스에 대해 다른 것을 고르지 않는 한 이 선택을 따릅니다(워크스페이스별 선택).
각 프로바이더는 하나의 레인입니다. 내 앱 사용(또는 아직 선택하지 않은 경우) 아래에서는 서버 자체 앱이 완전히 구성되어 있으면 레인은 그 앱에서 실행되고, 아니면 사용할 수 없습니다. Control Center 또는 사용자 지정 Connect를 쓰면 Connect가 제공하는 모든 레인을 Connect가 담당합니다. 서버 자체 앱은 저장만 되며 로그인, 서버 자동화, 서버가 보고하는 상태에 쓰이지 않습니다. 자체 선택을 한 워크스페이스는 그 선택에 따라 모든 레인을 실행합니다.
| 레인 | 자체 앱에 필요한 것 | Connect를 거칠 때 |
|---|---|---|
github |
앱 ID, 비공개 키, 클라이언트 ID, 클라이언트 시크릿 | 사람들이 공유 GitHub App에 로그인합니다 |
google |
클라이언트 ID와 클라이언트 시크릿 | 사람들이 Google Calendar를 연결합니다 |
linear |
클라이언트 ID | 사람들이 Linear에 로그인합니다 |
linear_app |
클라이언트 ID | 워크스페이스 관리자가 Linear의 앱 액터를 연결합니다 |
slack |
워크스페이스 자체 Slack 앱 연결 | 워크스페이스 관리자가 Slack을 공유 Slack 앱에 연결합니다 |
klipy |
KLIPY_APP_KEY |
Connect가 프록시하는 GIF 검색 |
일부만 구성된 자체 앱은 그 레인을 오류로 만들며, 결코 조용히 Connect로 폴백하지 않습니다. 내 앱 사용을 쓰는 워크스페이스는 프로바이더와 상관없이 서버 앱이나 어떤 Connect도 거치지 않습니다. 서버의 Connect 선택을 바꿔도 자체 선택을 한 워크스페이스에서 로그아웃되는 사람은 없습니다.
Connect가 보는 것과 결코 보지 않는 것
섹션 제목: “Connect가 보는 것과 결코 보지 않는 것”| Connect가 보는 것 | Connect가 결코 보지 않는 것 |
|---|---|
| 서버의 설치 ID와 요청 서명 | 소스 코드, 저장소 내용, diff, 풀 리퀘스트 텍스트 |
| 로그인 중, 로그인한 프로바이더 계정 | 티켓, 대화 기록, 워크스페이스 데이터베이스의 어떤 것 |
| 자격 증명이 속한 워크스페이스. 봉인 안의 불투명한 ID로서입니다 | 서버 자체 앱의 시크릿. 이 시크릿은 결코 서버를 떠나지 않습니다 |
| 저장소 하나에 대한 GitHub 토큰이 발급되는 저장소 | 저장된 상태의 갱신 토큰. 서버가 보관하는 봉인 안에만 존재합니다 |
| 서버에 바인딩된 Slack 팀 | Linear 시크릿. 서버가 Linear의 코드를 직접 교환합니다 |
| Klipy를 프록시할 때의 GIF 검색어 | 비밀번호, 페어링 키, 모델 프로바이더 키 |
| Slack 이벤트 참조(팀, 채널, 메시지 id)와 슬래시 명령 텍스트 | Slack 메시지 텍스트. Connect는 도착 즉시 이를 버리고, 서버가 Slack에서 메시지를 직접 읽습니다 |
Connect는 준비 중인 로그인, 논스, 캐시를 최대 10분 동안 보관하고, 시간당 사용량 카운터는 최대 두 시간 동안 보관합니다. 사람으로서 발급된 저장소 하나에 대한 GitHub 토큰은, 만료될 때까지(최대 8시간) 그것을 요청한 로그인에 봉인된 채 기록으로 남아 Connect가 다시 내주거나 연결 해제 시 회수할 수 있습니다. 오래 남는 기록은 Slack 바인딩(각 Slack 팀이 어느 서버에 묶여 있는지)과 폐기된 설치 ID뿐입니다. 오류에는 코드만 담기며 프로바이더의 응답은 결코 담기지 않습니다. 로그에는 설치 ID가 키가 적용된 해시로만 기록되고, GitHub 토큰은 GitHub 조직 감사 로그가 그 토큰에 대해 보여 주는 hashed_token으로만 기록되므로, 조직 소유자가 둘을 대조할 수 있습니다.
| 모드 | 설정 | 동작 |
|---|---|---|
| 미설정 | 새 서버 | 어떤 레인도 Connect를 쓰지 않습니다. 온보딩에서 서버 소유자에게 선택을 요청합니다 |
hosted |
Control Center의 앱 사용 | 오프라인으로 서명된 구성을 가진 https://connect.usectrl.dev. 서버 자체 앱은 사용되지 않습니다 |
custom |
사용자 지정 Connect 서버 사용 | HTTPS URL(루프백에서만 http)의 Connect. 처음 사용할 때 신뢰합니다. 서버 자체 앱은 사용되지 않습니다 |
off |
내 앱 사용 | 어떤 레인도 Connect를 쓰지 않습니다. 자체 앱만 사람들을 로그인시킵니다 |
서버의 환경이나 .env에 있는 CC_CONNECT_URL은 선택을 잠급니다. 값은 hosted, off,
또는 Connect URL입니다. 그러면 설정에 잠금이 표시되며 바꿀 수 없습니다.
이 빌드에는 호스팅 구성 키가 컴파일되어 있지 않으므로, 호스팅 모드는
hosted_unprovisioned를 보고하고 어떤 레인도 제공하지 않습니다. 자체 앱과 사용자 지정
Connect는 작동합니다.
호스팅 Connect는 단일 컨테이너에서 실행됩니다. 그 봉인 키와 공유 GitHub App의 비공개 키는 거기서 환경 변수이며, GitHub가 App의 비공개 키에 권장하는 것처럼 서명이나 복호화만 하는 금고의 키가 아닙니다. 이는 현재 구성의 알려진 공백입니다.
서버는 Connect의 구성을 최대 10분마다 읽고, 각 호출에서 최대 5초를 기다립니다. Connect에 연결할 수 없으면 마지막으로 유효했던 구성을 계속 사용하고, 설정에 그것이 오래되었다고 표시합니다.
워크스페이스별 선택
섹션 제목: “워크스페이스별 선택”설정 → 워크스페이스 → 연동 → Control Center Connect는 한 워크스페이스에 대해 서버의 선택을 덮어씁니다. 모든 멤버가 이를 볼 수 있고, 각 로그인이 어디에서 실행되는지도 볼 수 있습니다. 변경은 워크스페이스 관리자만 할 수 있습니다.
| 선택 | 동작 |
|---|---|
| 이 서버와 동일 | 기본값입니다. 워크스페이스는 서버 소유자가 고른 것에 따라 동작합니다. 옵션에 그 내용이 표시됩니다 |
| Control Center의 앱 사용 | Control Center의 호스팅 Connect. 서버가 무엇을 쓰든 상관없습니다 |
| 내 앱 사용 | 워크스페이스 자체 앱만 사용합니다: 워크스페이스의 GitHub App, Google 클라이언트, Linear 애플리케이션, Klipy 키, Slack 앱. 여기에 앱이 없는 프로바이더는 꺼지며, 일부만 구성된 앱은 설정 오류입니다 |
| 사용자 지정 Connect 서버 사용 | 워크스페이스가 지정한 HTTPS 주소의 Connect입니다. 사설 또는 로컬 네트워크 주소는 거부됩니다 |
- 이 서버와 동일 이외의 선택은 각 사람의 GitHub와 Linear 로그인을 워크스페이스 자체 슬롯에 보관하므로, 서버 전체의 로그인과 결코 섞이지 않습니다
- 전환하기 전에 먼저 확인을 요청합니다. 워크스페이스의 모든 사람이 새 앱을 통해 GitHub, Linear, Google Calendar에 다시 로그인해야 합니다
- 워크스페이스 자체 Slack 앱 연결은 모든 선택에서 작동합니다. Slack에 Control Center 추가는 선택을 따릅니다
CC_CONNECT_URL은 워크스페이스가 자체 Connect를 가지는 것도 막습니다. 워크스페이스는 서버를 따르거나 자체 앱을 쓸 수 있습니다- 워크스페이스의 사용자 지정 Connect는 그 워크스페이스에 대해서만 처음 사용할 때 신뢰됩니다. 여기서 새 앱 신뢰를 눌러도 서버나 다른 워크스페이스가 신뢰하는 것은 결코 바뀌지 않습니다
설치 신원
섹션 제목: “설치 신원”| 항목 | 무엇인가 |
|---|---|
| 설치 키 | 서버 시크릿 파일의 32바이트 시드(connect_install_key). 기기 페어링 키와는 별개입니다 |
| Connect별 키 | 시드와 Connect 주소에서 파생된 Ed25519 키. Connect에 보내는 모든 요청은 이 키로 서명됩니다(RFC 9421) |
| 설치 ID | 그 공개 키에서 파생된 26자. 설정과 cc_server connect status에 표시됩니다 |
같은 서버라도 Connect 주소마다 설치 ID가 다릅니다. ID는 키를 교체할 때만 바뀝니다.
봉인된 자격 증명
섹션 제목: “봉인된 자격 증명”Connect를 통한 로그인은 자격 증명 봉인을 돌려줍니다. 그것을 만든 Connect만 열 수 있는 암호화된 블롭입니다. 봉인은 프로바이더, Connect 주소, 설치 ID, 워크스페이스, 프로바이더 계정, 앱, 시크릿 세대에 묶입니다.
- 서버는 봉인과 그 봉인이 대상으로 한 설치 ID를 저장합니다. 액세스 토큰은 메모리에만 머뭅니다
- 갱신하려면 서버가 봉인을 돌려보내고, 새 액세스 토큰과 새 봉인을 받습니다
- 설치 ID나 Connect 주소가 더 이상 일치하지 않는 봉인은 다음에 읽힐 때 삭제되고, 그 사람은 다시 로그인합니다. 키 교체, 다른 Connect로의 전환, 다른 서버에 복원된 데이터 디렉터리 이후에 이런 일이 일어납니다
- Connect가 열 수 없는 봉인은
access_denied로 거부됩니다
GitHub 설치
섹션 제목: “GitHub 설치”공유 GitHub App의 설치는 모든 서버에서 쓸 수 있습니다. Connect는 어떤 서버가 그것을 쓸 수 있는지에 대한 기록을 보관하지 않습니다.
- 설정 → 워크스페이스 → 연동의 GitHub 앱 설치는 GitHub의 앱 설치 페이지를 엽니다. 링크는 서버가 Connect 구성의 앱 이름으로 만듭니다
- 저장소 하나에 대한 토큰은 앱이 저장소 소유자에게 설치되어 있고, 로그인한 사람에게 그 저장소에 대한 접근 권한이 있어야 합니다. 그 사람 본인의 토큰이며 역할에 맞게 제한되고, 그 이상은 결코 아닙니다
- 조직은 GitHub에서 Control Center를 제한할 수 있습니다. 설치를 제거하거나, 저장소 범위를 좁히거나, 사람을 제거하는 방식입니다
- 호출 중 사람만 할 수 있는 것, 예컨대 그 사람의 설치 목록 조회는, Connect가 저장소 하나에 대한 토큰이 아니라 사람 자신의 App 사용자 토큰을 서버에 건넵니다. 서버에 로그인하는 것은 그 토큰을 그 서버에 맡기는 것입니다
- GitHub IP 허용 목록을 강제하는 조직은 호스팅 Connect를 쓸 수 없습니다. 그 주소는 고정되어 있지 않기 때문입니다. 대신 자체 GitHub App을 등록하며, 이는 자신의 서버나 자신이 운영하는 Connect에서 합니다
- 연결 해제는 그 로그인만 취소합니다. Connect는 갱신 토큰을 한 번 사용하고 그것이 돌려주는 것을 삭제하며, 사용자 토큰과 Connect가 그 사람을 위해 발급한 저장소 하나짜리 토큰을 삭제합니다. 어딘가에 보관된 봉인의 사본은 작동을 멈춥니다. 다른 서버와 워크스페이스에서의 그 사람의 로그인은 계속 작동합니다. GitHub 계정에서 Control Center를 완전히 제거하려면 GitHub의 설정 → 애플리케이션 → 승인된 GitHub 앱 → 취소에서 취소하십시오
공유 봇
섹션 제목: “공유 봇”같은 Connect를 쓰는 모든 서버에 대해, App의 봇(as: app)으로 발급된 토큰은 GitHub에서 같은 봇으로 표시됩니다. GitHub는 그 서버들을 구별할 수 없습니다.
- 모든 서버는 봇이 읽고 댓글을 달도록 할 수 있습니다:
read,review,comment(이슈와 풀 리퀘스트의 댓글, 레이블, 담당자, 반응) - 봇으로서 풀 리퀘스트를 리뷰하는 것(
bot, 풀 리퀘스트에 쓰기)은 Connect 운영자가CONNECT_GITHUB_REVIEW_BOT_INSTALLS에 나열한 서버에만 허용됩니다. 그 밖의 모든 서버는needs_requester로 응답받으며, 리뷰는 책임 있는 사람 본인의 토큰으로 게시됩니다. 이 토큰은 GitHub가 그 사람으로 제한하므로, 리뷰는 그 사람의 이름으로 표시됩니다. 이는 AI 리뷰 게시, 리뷰 댓글, 리뷰어 요청을 포함합니다 - 푸시, 브랜치 생성, 풀 리퀘스트 열기(
write)는 공유 봇으로 발급되지 않습니다. 항상 요청한 사람의 로그인을 씁니다 - 풀 리퀘스트 승인은 어떤 토큰으로도 자동화되지 않습니다
- 자체 GitHub App을 가진 서버나 워크스페이스는 리뷰를 포함해 이 모든 것에 봇을 유지합니다
조직 소유자와 구성원이 알아야 할 것
섹션 제목: “조직 소유자와 구성원이 알아야 할 것”- 누군가 로그인한 서버는 그 사람의 App 사용자 토큰을 보유합니다. 토큰당 최대 8시간이며, 연결을 해제할 때까지 갱신됩니다. 그 사람이 접근할 수 있는, 공유 App이 설치된 모든 저장소에서 그 사람을 대신해 행동할 수 있습니다. Connect는 서버를 영구히 차단할 수 있지만(폐기되거나 거부된 설치), 이미 건넨 토큰은 만료될 때까지 유효합니다
- 조직에 공유 GitHub App을 설치하면, 어떤 구성원이든 로그인하는 모든 Control Center 서버에 대해 동의하게 됩니다. 한 서버에 대해서만 동의하는 것이 아닙니다
- 위와 같이 봇은 공유됩니다. 조직은 GitHub에서 어느 서버가 봇으로 행동했는지 구별할 수 없습니다
- 자신만의 경계를 원하는 조직은 자체 GitHub App을 등록하고 자체 Connect를 운영하거나(Connect 서버 실행), 자신의 서버에서 App을 구성합니다
구성 신뢰
섹션 제목: “구성 신뢰”| Connect | 서버가 그 구성을 신뢰하는 방법 |
|---|---|
| 호스팅 | 빌드에 컴파일된 키로 Ed25519 서명을 검증합니다. 지금까지 본 가장 높은 에포크보다 낮은 에포크는 거부합니다(rollback) |
| 사용자 지정 | 처음 사용할 때 GitHub 앱 ID와 클라이언트 ID, Google과 Linear의 클라이언트 ID, Slack 앱 ID와 클라이언트 ID를 고정합니다. 변경되면 서버 소유자가 새 앱 신뢰를 누를 때까지 Connect 로그인이 일시 중지됩니다(pins_changed) |
서버의 Connect 설정은 서버 소유자 전용입니다.
| 작업 | 하는 일 |
|---|---|
connect.status |
모드, URL, 잠금, 설치 ID, 상태, 구성 에포크, 각 레인의 출처 |
connect.configure |
hosted, custom(url과 함께) 또는 off를 설정합니다 |
connect.test |
구성을 다시 가져와 상태를 보고합니다 |
connect.confirmPins |
사용자 지정 Connect의 변경된 식별자를 받아들입니다 |
connect.rotateKey |
새 설치 키와 새 설치 ID를 발급합니다(force는 Connect가 이전 키를 폐기하지 못해도 교체합니다). 설치 키 교체를 참고하십시오 |
워크스페이스의 선택은 자체 작업을 가지며, 각각 워크스페이스를 지정합니다:
| 작업 | 대상 | 내용 |
|---|---|---|
workspaceConnect.status |
모든 멤버 | 선택, 해석된 결과, 상태, 각 프로바이더의 출처. 설치 ID와 대기 중인 고정은 관리자만 |
workspaceConnect.set |
워크스페이스 관리자 | inherit, hosted, custom(url 포함) 또는 own을 설정합니다 |
workspaceConnect.test |
워크스페이스 관리자 | 워크스페이스의 Connect 구성을 다시 가져오고 상태를 보고합니다 |
workspaceConnect.confirmPins |
워크스페이스 관리자 | 워크스페이스의 사용자 지정 Connect가 바뀐 식별자를 수락합니다 |
로그인 자체는 oauth.lanes, oauth.begin, oauth.status, oauth.complete,
oauth.connections, oauth.disconnect를 사용합니다. 그 사람은 항상 로그인한
호출자입니다.
Connect를 통한 로그인
섹션 제목: “Connect를 통한 로그인”- 서버가 Connect에 레인 시작을 요청하고 프로바이더의 승인 URL을 받으며, 이를 표시하기 전에 확인합니다. GitHub는 항상 계정 선택 화면을 보여 줍니다
- 사람이 브라우저에서 승인합니다. 프로바이더는 Connect로 돌아옵니다
- Connect는 로그인을 시작한 서버가 그 사람으로서 무엇을 할 수 있는지, 그리고 얼마나 오래 할 수 있는지를 보여 줍니다. Connect는 그 서버를 누가 운영하는지 알 수 없으므로, 페이지는 로그인을 직접 시작한 경우에만 계속하도록 요청하고, 누군가 링크를 보낸 경우에는 닫으라고 요청합니다. 브라우저가 로그인을 시작한 네트워크와 다른 네트워크에 있으면 페이지가 그렇다고 알려 줍니다. 호스팅 서버나 다른 기기에서는 정상이지만, 피싱도 바로 이렇게 보입니다. 취소는 로그인을 끝냅니다. 프로바이더의 코드는 결코 사용되지 않습니다. 각 페이지는 한 번만 응답하며, Connect가 방금 보여 준 페이지에서 오지 않은 응답은 거부됩니다
- 계속을 누르면 Connect가 8자리 코드와
control-center://oauth-done링크를 표시합니다. 코드를 받는 사람은 방금 승인된 접근 권한을 얻게 되므로, 코드는 로그인을 시작한 곳에만 전달되어야 합니다 - 사람이 앱에 코드를 입력하거나 링크를 따라갑니다. 서버는 코드와 요청에 대한 자체 증명으로 로그인을 회수합니다
로그인은 10분 후에 만료됩니다. 잘못된 코드를 다섯 번 입력하면 끝납니다. 이 앱이 시작하지
않은 링크는 여기서 시작한 로그인이 아닙니다로 거부됩니다. Connect는 한 네트워크 주소가
시작할 수 있는 로그인 수와, GitHub 토큰이 발급되는 빈도를 제한합니다. 제한은 사람과 서버별,
서버를 가로지르는 사람별, 주소별, 그리고 앱 전체에 대해 적용됩니다. 새 로그인은 자체 예산을
가지므로, 다른 사람들이 필요로 하는 갱신을 결코 지연시키지 않습니다. 제한을 넘으면 호출은
rate_limited와 함께 거부되며, 서버는 누구도 로그아웃시키지 않고 나중에 다시 시도합니다. 그
사람의 제한을 넘은 로그인은 GitHub에서 취소되고 거부됩니다.
설치 키 교체
섹션 제목: “설치 키 교체”설정 → 서버 → 싱글 사인온의 Control Center Connect 카드에 있는 키 교체로만 서버 소유자가 키를 교체할 수 있습니다. 이를 위한 명령은 없습니다. 교체는 다음을 수행합니다.
- Connect를 거치는 모든 레인에서 모두를 로그아웃시킵니다. 이전 키가 사용되었던 각 Connect 서버에 대해, 서버는 거기서 보유한 GitHub와 Slack 로그인을 취소합니다(Google 로그인은 취소할 것이 없으며 만료됩니다)
- 그 각 Connect 서버에서 이전 설치 ID를 폐기합니다. 이는 이전 키로 서명하고, 그 Connect로부터 서버가 보유한 자격 증명 봉인 하나로 증명합니다. 그 뒤로 Connect는 이전 키로 된 모든 요청을 거부하므로, 이 서버에서 가져온 봉인이나 이전 키의 사본은 쓸모가 없으며, 이전 ID에 묶여 있던 Slack 워크스페이스는 다시 연결할 수 있도록 풀려납니다. 이미 건넨 토큰은 만료될 때까지 유효합니다(봇 토큰은 1시간, 사람의 토큰은 8시간). 이 서버가 봉인을 보유하지 않은 Connect 서버는 폐기할 것이 없으므로 건너뜁니다
- 그다음 서버에 새 설치 키와 새 설치 ID를 부여합니다
- Connect 서버에 연결할 수 없거나 이전 ID의 폐기를 거부하면, 키를 바꾸기 전에 멈추고 Connect가 이전 키를 폐기하지 못했습니다를 표시합니다. 그래도 교체는 어쨌든 키를 바꿉니다. 그러면 이전 설치 ID는 토큰이 만료될 때까지 그 Connect에서 계속 사용할 수 있으며, GitHub의 경우 최대 8시간입니다
- 서버 자체 앱을 통한 로그인은 그대로 둡니다
- 사용자 지정 Connect의 허용 목록에 새 설치 ID를 추가해야 합니다
상태 코드
섹션 제목: “상태 코드”| 코드 | 의미 |
|---|---|
hosted_unprovisioned |
이 빌드에는 호스팅 구성 키가 없습니다 |
signature |
호스팅 구성이 서명 검사에 실패했습니다 |
rollback |
Connect가 서버가 이미 본 것보다 오래된 구성을 제공했습니다 |
unreachable |
서버가 Connect에 연결할 수 없습니다 |
install_blocked |
Connect가 이 설치 ID를 허용하지 않거나, 이 ID는 폐기되었습니다 |
pins_changed |
사용자 지정 Connect가 다른 앱 식별자를 알렸습니다 |
protocol |
Connect가 이 서버가 이해하지 못하는 형식으로 응답했습니다 |