GitLab Shell 개발 지침

파이프라인 상태 커버리지 리포트 코드 클리메이트

GitLab Shell은 GitLab의 Git SSH 세션을 처리하고 인가된 키 디렉터리을 수정합니다. GitLab Shell은 유닉스 셸이나 Bash 또는 Zsh를 대체하는 것이 아닙니다.

GitLab은 SSH를 통해 Git LFS 인증을 지원합니다.

요구 사항

GitLab Shell은 Go로 작성되었으며 빌드하기 위해 Go 컴파일러가 필요합니다. 여전히 빌드하고 테스트하기 위해 Ruby가 필요하지만 실행에는 필요하지 않습니다.

Omnibus 설치에서 GitLab Shell은 포트 22에서 실행됩니다. 일반 SSH 서비스를 사용하려면 대체 포트에 구성하세요.

현재 버전의 Go을 다운로드하고 설치하세요. 우리는 Go 릴리즈 정책을 따르며 다음을 지원합니다:

  • 최신 안정 버전
  • 이전 두 개 주요 버전

버전

GitLab Shell과 관련된 두 가지 버전 파일이 있습니다:

GitLab 팀원은 내부 Slack 채널인 #announcements를 모니터링할 수도 있습니다.

GitLab Shell 작업 방식

SSH를 통해 GitLab 서버에 액세스하면 GitLab Shell이 다음을 수행합니다:

  1. 미리 정의된 Git 명령(git push, git pull, git fetch)으로 제한합니다.
  2. GitLab Rails API를 호출하여 사용자의 인가 여부와 리포지터리의 Gitaly 서버를 확인합니다.
  3. SSH 클라이언트와 Gitaly 서버 간에 데이터를 복사합니다.

만약 HTTP(S)를 통해 GitLab 서버에 액세스하면 gitlab-workhorse로 이동합니다.

SSH를 통한 git pull

graph LR A[Git pull] --> |SSH를 통해| B[gitlab-shell] B -->|API 호출| C[gitlab-rails<br>인가] C -->|수락 또는 거절| D[Gitaly 세션]

SSH를 통한 git push

git push 명령은 gitlab-rails가 푸시를 수락한 후에 수행됩니다:

graph LR subgraph 사용자 시작 A[Git push] -->|SSH를 통해| B[gitlab-shell] end subgraph Gitaly B -->|Gitaly 세션 설정| C[gitlab-shell 프리-리시브 훅] C -->|API 인가 호출| D[Gitlab-rails] D --> E[푸시 수락 또는 거절] end

전체 기능 디렉터리

authorized_keys 수정

GitLab Shell은 클라이언트 기기의 authorized_keys 파일을 수정합니다.

GitLab Shell에 기여

GitLab Shell에 기여하려면:

  1. GitLab API 액세스 및 내부 API를 통해 Redis에 도달할 수 있는지 확인하세요: make check
  2. gitlab-shell 이진 파일을 컴파일하여 bin/에 배치하세요: make compile
  3. make install을 실행하여 gitlab-shell 이진 파일을 빌드하고 설치하세요. 기본 위치는 /usr/local입니다. 이를 변경하려면 PREFIX 및 DESTDIR 환경 변수를 설정하세요.
  4. 단일 기기에서 소스에서 GitLab을 설치하려면 make setup을 실행하세요. 이 명령은 GitLab Shell 이진 파일을 컴파일하고 파일 시스템에 올바른 권한으로 경로를 만듭니다. 이 명령은 설치 방법 설명서에서 지시하는 경우에만 실행하세요.

더 많은 정보는 CONTRIBUTING.md를 참조하세요.

테스트 실행

기여할 때 테스트를 실행하세요:

  1. bundle install 및 make test로 테스트를 실행하세요.
  2. Gofmt를 실행하세요: make verify

  3. 테스트 및 verify를 모두 실행하세요 (기본 Makefile 대상): 

    bundle install
make validate
  4. 필요한 경우 Gitaly를 구성하세요.

로컬 테스트를 위해 Gitaly 구성

일부 테스트에는 Gitaly 서버가 필요합니다. docker-compose.yml 파일은 Gitaly를 8075 포트에서 실행합니다. 테스트에게 Gitaly 위치를 알리려면 GITALY_CONNECTION_INFO를 설정하세요: 

export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
make test

만약 GITALY_CONNECTION_INFO가 설정되지 않으면 테스트 스위트가 실행되지만 Gitaly를 필요로 하는 테스트는 건너뜁니다. 테스트는 항상 CI 환경에서 실행됩니다.

요율 제한

GitLab Shell은 사용자 계정 및 프로젝트별로 Git 작업에 대한 요율 제한을 수행합니다. GitLab Shell은 Git 작업 요청을 수락하고 그 후에 Redis를 백업하는 Rails 요율 제한기를 호출합니다. 사용자 + 프로젝트가 요율 제한을 초과하면 GitLab Shell은 해당 사용자 + 프로젝트에 대한 추가 연결 요청을 드랍합니다.

요율 제한은 Git 명령(플러빙) 수준에서 적용됩니다. 각 명령에는 분당 600개의 요율 제한이 있습니다. 예를 들어 git push는 분당 600개이고, git pull은 또 다른 600개입니다.

동일한 플러빙 명령을 사용하기 때문에 git-upload-pack, git pull, git clone은 요율 제한 목적상 동일한 명령으로 간주됩니다.

Gitaly에도 요율 제한기가 있지만 GitLab Shell(Rails)에서 요율 제한을 초과하면 Gitaly에 요청을 보내지 않습니다.

GitLab Shell 로그

일반적으로 로그를 검사하여 GitLab Shell 또는 gitlab-sshd 세션의 구조를 결정할 수 있지만 내용은 확인할 수 없습니다. 몇 가지 안내 사항:

  • 로깅에는 gitlab.com/gitlab-org/labkit/log를 사용합니다.
  • 항상 상관 ID를 포함하세요.
  • 로그 메시지는 불변하고 고유해야 합니다. log.WithField, log.WithFields, 또는 log.WithError를 사용하여 필드에 보조 정보를 포함하세요.
  • 성공적인 경우와 오류 경우에 로깅하세요.
  • 너무 많이 로깅하는 것이 부족하게 로깅하는 것보다 좋습니다. 메시지가 너무 자세하다고 생각된다면 메시지를 제거하기 전에 로그 레벨을 낮추는 것을 고려하세요.
graph LR a2 --> b2 a2 --> b3 a2 --> b4 b2 --> c1 b3 --> c1 b4 --> c1 c2 --> d1 c2 --> d2 c2 --> d3 d1 --> e1 d2 --> e1 d3 --> e1 a1[Cloudflare] --> a2[TCP<br/> load balancer] e1[Git] subgraph HAProxy Fleet b2[HAProxy] b3[HAProxy] b4[HAProxy] end subgraph GKE c1[내부 TCP<br/> 로드 밸런서<br/>포트 2222] --> c2[GitLab-shell<br/> 포드] end subgraph Gitaly d1[Gitaly] d2[Gitaly] d3[Gitaly] end

GitLab Shell 아키텍처

sequenceDiagram participant Git on client participant SSH server participant AuthorizedKeysCommand participant GitLab Shell participant Rails participant Gitaly participant Git on server Note left of Git on client: git fetch Git on client->>+SSH server: ssh git fetch-pack 요청 SSH server->>+AuthorizedKeysCommand: gitlab-shell-authorized-keys-check git AAAA... AuthorizedKeysCommand->>+Rails: GET /internal/api/authorized_keys?key=AAAA... Note right of Rails: 키 ID 조회 Rails-->>-AuthorizedKeysCommand: 200 OK, command="gitlab-shell upload-pack key_id=1" AuthorizedKeysCommand-->>-SSH server: command="gitlab-shell upload-pack key_id=1" SSH server->>+GitLab Shell: gitlab-shell upload-pack key_id=1 GitLab Shell->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1 Note right of Rails: 인증 확인 Rails-->>-GitLab Shell: 200 OK, { gitaly: ... } GitLab Shell->>+Gitaly: SSHService.SSHUploadPack 요청 Gitaly->>+Git on server: git upload-pack 요청 Note over Git on client,Git on server: Git 클라이언트와 서버 간의 양방향 통신 Git on server-->>-Gitaly: git upload-pack 응답 Gitaly -->>-GitLab Shell: SSHService.SSHUploadPack 응답 GitLab Shell-->>-SSH server: gitlab-shell upload-pack 응답 SSH server-->>-Git on client: ssh git fetch-pack 응답

관련 주제