%%{init: {"flowchart": { "useMaxWidth": false } }}%%
graph TB
  %% Component declarations and formatting
  HTTP((HTTP/HTTPS))
  SSH((SSH))
  GitLabPages(GitLab Pages)
  GitLabWorkhorse(GitLab Workhorse)
  GitLabShell(GitLab Shell)
  Gitaly(Gitaly)
  Puma("Puma (Gitlab Rails)")
  Sidekiq("Sidekiq (GitLab Rails)")
  PostgreSQL(PostgreSQL)
  Redis(Redis)
HTTP -- TCP 80,443 --> NGINX
SSH -- TCP 22 --> GitLabShell
NGINX -- TCP 8090 --> GitLabPages
NGINX --> GitLabWorkhorse
GitLabShell --> Gitaly
GitLabShell --> GitLabWorkhorse
GitLabWorkhorse --> Gitaly
GitLabWorkhorse --> Puma
GitLabWorkhorse --> Redis
Sidekiq --> PostgreSQL
Sidekiq --> Redis
Puma --> PostgreSQL
Puma --> Redis
Puma --> Gitaly
Gitaly --> GitLabWorkhorse

%%{init: {"flowchart": { "useMaxWidth": false } }}%%
graph LR
  %% Anchor items in the appropriate subgraph.
  %% Link them where the destination* is.
subgraph Clients
Browser((Browser))
Git((Git))
end
%% External Components / Applications
Geo{{GitLab Geo}} -- TCP 80, 443 --> HTTP
Geo -- TCP 22 --> SSH
Geo -- TCP 5432 --> PostgreSQL
Runner{{GitLab Runner}} -- TCP 443 --> HTTP
K8sAgent{{GitLab agent}} -- TCP 443 --> HTTP
%% GitLab Application Suite
subgraph GitLab
subgraph Ingress
HTTP[[HTTP/HTTPS]]
SSH[[SSH]]
NGINX[NGINX]
GitLabShell[GitLab Shell]
    %% inbound/internal
    Browser -- TCP 80,443 --> HTTP
    Git -- TCP 80,443 --> HTTP
    Git -- TCP 22 --> SSH
    HTTP -- TCP 80, 443 --> NGINX
    SSH -- TCP 22 --> GitLabShell
end

subgraph GitLab Services
    %% inbound from NGINX
    NGINX --> GitLabWorkhorse
    NGINX -- TCP 8090 --> GitLabPages
    NGINX -- TCP 8150 --> GitLabKas
    NGINX --> Registry
    %% inbound from GitLabShell
    GitLabShell --> GitLabWorkhorse

    %% services
    Puma["Puma (GitLab Rails)"]
    Puma <--> Registry
    GitLabWorkhorse[GitLab Workhorse] <--> Puma
    GitLabKas[GitLab agent server] --> GitLabWorkhorse
    GitLabPages[GitLab Pages] --> GitLabWorkhorse
    Mailroom
    Sidekiq
end

subgraph Integrated Services
    %% Grafana
    Grafana
    NGINX --> Grafana
end

subgraph Metadata
    %% PostgreSQL
    PostgreSQL
    PostgreSQL --> Consul

    %% Consul and inbound
    Consul
    Puma ---> Consul
    Sidekiq ---> Consul
    Migrations --> PostgreSQL

    %% PgBouncer and inbound
    PgBouncer
    PgBouncer --> Consul
    PgBouncer --> PostgreSQL
    Sidekiq --> PgBouncer
    Puma --> PgBouncer
end

subgraph State
    %% Redis and inbound
    Redis
    Puma --> Redis
    Sidekiq --> Redis
    GitLabWorkhorse --> Redis
    Mailroom --> Redis
    GitLabKas --> Redis

    %% Sentinel and inbound
    Sentinel <--> Redis
    Puma --> Sentinel
    Sidekiq --> Sentinel
    GitLabWorkhorse --> Sentinel
    Mailroom --> Sentinel
    GitLabKas --> Sentinel
end

subgraph Git Repositories
    %% Gitaly / Praefect
    Praefect --> Gitaly
    GitLabKas --> Praefect
    GitLabShell --> Praefect
    GitLabWorkhorse --> Praefect
    Puma --> Praefect
    Sidekiq --> Praefect
    Praefect <--> PraefectPGSQL[PostgreSQL]
    %% Gitaly makes API calls
    %% Ordered here to ensure placement.
    Gitaly --> GitLabWorkhorse
end

subgraph Storage
    %% ObjectStorage and inbound traffic
    ObjectStorage["Object storage"]
    Puma -- TCP 443 --> ObjectStorage
    Sidekiq -- TCP 443 --> ObjectStorage
    GitLabWorkhorse -- TCP 443 --> ObjectStorage
    Registry -- TCP 443 --> ObjectStorage
    GitLabPages -- TCP 443 --> ObjectStorage
    %% Gitaly can perform repository backups to object storage.
    Gitaly --> ObjectStorage
end

subgraph Monitoring
    %% Prometheus
    Grafana -- TCP 9090 --> Prometheus[Prometheus]
    Prometheus -- TCP 80, 443 --> Puma
    RedisExporter[Redis Exporter] --> Redis
    Prometheus -- TCP 9121 --> RedisExporter
    PostgreSQLExporter[PostgreSQL Exporter] --> PostgreSQL
    PgBouncerExporter[PgBouncer Exporter] --> PgBouncer
    Prometheus -- TCP 9187 --> PostgreSQLExporter
    Prometheus -- TCP 9100 --> NodeExporter[Node Exporter]
    Prometheus -- TCP 9168 --> GitLabExporter[GitLab Exporter]
    Prometheus -- TCP 9127 --> PgBouncerExporter
    Prometheus --> Alertmanager
    GitLabExporter --> PostgreSQL
    GitLabExporter --> GitLabShell
    GitLabExporter --> Sidekiq

    %% Alertmanager
    Alertmanager -- TCP 25 --> SMTP
end

%% end subgraph GitLab
end
subgraph External
subgraph External Services
SMTP[SMTP Gateway]
LDAP
    %% Outbound SMTP
    Sidekiq -- TCP 25 --> SMTP
    Puma -- TCP 25 --> SMTP
    Mailroom -- TCP 25 --> SMTP

    %% Outbound LDAP
    Puma -- TCP 369 --> LDAP
    Sidekiq -- TCP 369 --> LDAP

    %% Elasticsearch
    Elasticsearch
    Puma -- TCP 9200 --> Elasticsearch
    Sidekiq -- TCP 9200 --> Elasticsearch
    Elasticsearch --> Praefect

    %% Zoekt
    Zoekt --> Praefect
end
subgraph External Monitoring
    %% Sentry
    Sidekiq -- TCP 80, 443 --> Sentry
    Puma -- TCP 80, 443 --> Sentry

    %% Jaeger
    Jaeger
    Sidekiq -- UDP 6831 --> Jaeger
    Puma -- UDP 6831 --> Jaeger
    Gitaly -- UDP 6831 --> Jaeger
    GitLabShell -- UDP 6831 --> Jaeger
    GitLabWorkhorse -- UDP 6831 --> Jaeger
end

%% end subgraph External
end
click Alertmanager "#alertmanager"
click Praefect "#praefect"
click Geo "#gitlab-geo"
click NGINX "#nginx"
click Runner "#gitlab-runner"
click Registry "#registry"
click ObjectStorage "#object-storage"
click Gitaly "#gitaly"
click Jaeger "#jaeger"
click GitLabWorkhorse "#gitlab-workhorse"
click LDAP "#ldap-authentication"
click Puma "#puma"
click GitLabShell "#gitlab-shell"
click SSH "#ssh-request-22"
click Sidekiq "#sidekiq"
click Sentry "#sentry"
click GitLabExporter "#gitlab-exporter"
click Elasticsearch "#elasticsearch"
click Migrations "#database-migrations"
click PostgreSQL "#postgresql"
click Consul "#consul"
click PgBouncer "#pgbouncer"
click PgBouncerExporter "#pgbouncer-exporter"
click RedisExporter "#redis-exporter"
click Redis "#redis"
click Prometheus "#prometheus"
click Grafana "#grafana"
click GitLabPages "#gitlab-pages"
click PostgreSQLExporter "#postgresql-exporter"
click SMTP "#outbound-email"
click NodeExporter "#node-exporter"

sequenceDiagram
    participant Git on client
    participant NGINX
    participant Workhorse
    participant Rails
    participant Gitaly
    participant Git on server
Note left of Git on client: git fetch<br/>info-refs
Git on client->>+Workhorse: GET /info/refs?service=git-upload-pack
Workhorse->>+Rails: GET /info/refs?service=git-upload-pack
Note right of Rails: Auth check
Rails-->>-Workhorse: Gitlab::Workhorse.git_http_ok
Workhorse->>+Gitaly: SmartHTTPService.InfoRefsUploadPack request
Gitaly->>+Git on server: git upload-pack --stateless-rpc --advertise-refs
Git on server-->>-Gitaly: git upload-pack response
Gitaly-->>-Workhorse: SmartHTTPService.InfoRefsUploadPack response
Workhorse-->>-Git on client: 200 OK

Note left of Git on client: git fetch<br/>fetch-pack
Git on client->>+Workhorse: POST /git-upload-pack
Workhorse->>+Rails: POST /git-upload-pack
Note right of Rails: Auth check
Rails-->>-Workhorse: Gitlab::Workhorse.git_http_ok
Workhorse->>+Gitaly: SmartHTTPService.PostUploadPack request
Gitaly->>+Git on server: git upload-pack --stateless-rpc
Git on server-->>-Gitaly: git upload-pack response
Gitaly-->>-Workhorse: SmartHTTPService.PostUploadPack response
Workhorse--&gt;&gt;-Git on client: 200 OK</code></pre></details></div>

git push의 시퀀스도 비슷하지만, git-upload-pack 대신
git-receive-pack을 사용합니다.
SSH 요청(22)#
SSH를 통한 Git 작업은 상태 저장(stateful) 프로토콜을 사용할 수 있으며, 이는
Git 문서에 설명되어 있지만,
이러한 작업의 처리 책임은 여러 GitLab 컴포넌트에 나뉘어 있습니다.
어떤 GitLab 컴포넌트도 SSH를 직접 사용하지 않습니다. 모든 SSH 연결은
클라이언트 머신의 Git과 연결을 종료하는 SSH 서버 사이에서 이루어집니다.
SSH 서버에는 모든 연결이 git 사용자로 인증되며, GitLab
사용자는 클라이언트가 제시하는 SSH 키로 구분됩니다.
다음은 빠른 SSH 키 조회가 활성화되어 있다고 가정한 git fetch의
시퀀스 다이어그램입니다. AuthorizedKeysCommand는
GitLab Shell이 제공하는 실행 파일입니다.
Mermaid 다이어그램 (27줄)
소스 코드 보기
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-&gt;&gt;+SSH server: ssh git fetch-pack request
SSH server-&gt;&gt;+AuthorizedKeysCommand: gitlab-shell-authorized-keys-check git AAAA...
AuthorizedKeysCommand-&gt;&gt;+Rails: GET /internal/api/authorized_keys?key=AAAA...
Note right of Rails: Lookup key ID
Rails--&gt;&gt;-AuthorizedKeysCommand: 200 OK, command="gitlab-shell upload-pack key_id=1"
AuthorizedKeysCommand--&gt;&gt;-SSH server: command="gitlab-shell upload-pack key_id=1"
SSH server-&gt;&gt;+GitLab Shell: gitlab-shell upload-pack key_id=1
GitLab Shell-&gt;&gt;+Rails: GET /internal/api/allowed?action=upload_pack&amp;key_id=1
Note right of Rails: Auth check
Rails--&gt;&gt;-GitLab Shell: 200 OK, { gitaly: ... }
GitLab Shell-&gt;&gt;+Gitaly: SSHService.SSHUploadPack request
Gitaly-&gt;&gt;+Git on server: git upload-pack request
Note over Git on client,Git on server: Bidirectional communication between Git client and server
Git on server--&gt;&gt;-Gitaly: git upload-pack response
Gitaly --&gt;&gt;-GitLab Shell: SSHService.SSHUploadPack response
GitLab Shell--&gt;&gt;-SSH server: gitlab-shell upload-pack response
SSH server--&gt;&gt;-Git on client: ssh git fetch-pack response</code></pre></details></div>

git push 작업도 매우 비슷하지만, git upload-pack 대신
git receive-pack을 사용합니다.
빠른 SSH 키 조회가 활성화되지 않은 경우 SSH 서버는
~git/.ssh/authorized_keys 파일을 읽어 특정
SSH 세션에 대해 실행할 명령을 결정합니다. 이 파일은 Rails의 AuthorizedKeysWorker가
최신 상태로 유지하며, 사용자가 SSH 키를 수정할 때마다 실행되도록 예약됩니다.
키 대신 SSH 인증서를 사용할 수도 있습니다.
이 경우 AuthorizedKeysCommand가
AuthorizedPrincipalsCommand로 대체됩니다. 이 명령은 인증서에서 사용자 이름을 추출하며
Rails 내부 API를 사용하지 않습니다. 이 사용자 이름은 이후
/api/internal/allowed 호출에서 key_id 대신 쓰입니다.
GitLab Shell에는 2단계 인증 코드 재설정처럼
Gitaly가 관여하지 않는 작업도 몇 가지 있습니다. 이러한 작업도 같은 방식으로 처리되지만,
Gitaly로의 왕복은 없습니다. Rails가 내부 API 호출의 일부로
작업을 수행하고, GitLab Shell은
응답을 사용자에게 직접 스트리밍합니다.
시스템 레이아웃#
그림에서 ~git은 Git 사용자의 홈 디렉터리를 뜻하며, 일반적으로 /home/git입니다.
GitLab은 주로 git 사용자로서 /home/git 사용자 홈 디렉터리 안에 설치됩니다. 홈 디렉터리에는 GitLab 서버 소프트웨어와 리포지터리가 있습니다(리포지터리 위치는 설정할 수 있습니다).
bare 리포지터리는 /home/git/repositories에 있습니다. GitLab은 Ruby on Rails 애플리케이션이므로, 내부 동작의 세부 사항은 Ruby on Rails 애플리케이션이 동작하는 방식을 학습하여 알 수 있습니다.
SSH로 리포지터리를 제공하기 위해 /home/git/gitlab-shell에 설치되는 GitLab Shell이라는 애드온 애플리케이션이 있습니다.
설치 폴더 요약#
git 사용자 홈 디렉터리의 디렉터리 구조를 참고합니다.
프로세스#
ps aux | grep '^git'

GitLab은 동작하는 데 여러 컴포넌트가 필요합니다. 영구 데이터베이스
(PostgreSQL)와 Redis 데이터베이스가 필요하며, Apache httpd 또는 NGINX로 Puma에 proxypass합니다.
이 모든 컴포넌트는 GitLab과는 다른 시스템 사용자로 실행해야 합니다
(예: git이 아니라 postgres, redis, www-data).
git 사용자로서 Sidekiq와 Puma(기본적으로 포트 8080에서
실행되는 단순한 Ruby HTTP 서버)를 시작합니다. GitLab 사용자 아래에는 보통 4개의
프로세스가 있습니다. puma master(프로세스 1개), puma cluster worker
(프로세스 2개), sidekiq(프로세스 1개)입니다.
리포지터리 접근#
리포지터리는 HTTP 또는 SSH로 접근합니다. HTTP 클론/푸시/풀은 GitLab API를 사용하고 SSH 클론은 (앞서 설명한) GitLab Shell이 처리합니다.
문제 해결#
자세한 내용은 README를 참고합니다.
서비스의 init 스크립트#
GitLab init 스크립트는 Puma와 Sidekiq를 시작하고 중지합니다.
/etc/init.d/gitlab
Usage: service gitlab {start|stop|restart|reload|status}

Redis(키-값 저장소/비영구 데이터베이스):
/etc/init.d/redis
Usage: /etc/init.d/redis {start|stop|status|restart|condrestart|try-restart}

SSH 데몬:
/etc/init.d/sshd
Usage: /etc/init.d/sshd {start|stop|restart|reload|force-reload|condrestart|try-restart|status}

웹 서버(다음 중 하나):
/etc/init.d/httpd
Usage: httpd {start|stop|restart|condrestart|try-restart|force-reload|reload|status|fullstatus|graceful|help|configtest}

$ /etc/init.d/nginx
Usage: nginx {start|stop|restart|reload|force-reload|status|configtest}

영구 데이터베이스:
$ /etc/init.d/postgresql
Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [version ..]

서비스의 로그 위치#
GitLab(Puma와 Sidekiq 로그 포함):

/home/git/gitlab/log/에는 보통 application.log, production.log, sidekiq.log, puma.stdout.log, git_json.log, puma.stderr.log가 있습니다.

GitLab Shell:

/home/git/gitlab-shell/gitlab-shell.log

SSH:

/var/log/auth.log 인증 로그(Ubuntu).
/var/log/secure 인증 로그(RHEL).

NGINX:

/var/log/nginx/에는 오류 및 접근 로그가 있습니다.

Apache httpd:

Apache 로그 설명.
/var/log/apache2/에는 오류 및 출력 로그가 있습니다(Ubuntu).
/var/log/httpd/에는 오류 및 출력 로그가 있습니다(RHEL).

Redis:

/var/log/redis/redis.log. 로그 순환된 로그도 함께 있습니다.

PostgreSQL:

/var/log/postgresql/*

GitLab 관련 설정 파일#
GitLab의 설정 파일은 /home/git/gitlab/config/*에 있습니다. 자주 참조되는
설정 파일은 다음과 같습니다.

gitlab.yml: GitLab Rails 설정
puma.rb: Puma 웹 서버 설정
database.yml: 데이터베이스 연결 설정

GitLab Shell의 설정 파일은 /home/git/gitlab-shell/config.yml에 있습니다.
GitLab Rails에 새 설정 추가#
gitlab.yml에 속하는 설정은 다음과 관련된 것입니다.

애플리케이션이 여러 서비스에 걸쳐 연결되는 방식. 예: Gitaly 주소, Redis 주소, Postgres 주소, Consul 주소.
분산 추적 설정과 일부 관측성 설정. 예: 히스토그램 버킷 경계.
Rails 초기화 중, 경우에 따라 Postgres 연결이 수립되기 전에 설정해야 하는 모든 것.

그 밖의 많은 설정은 앱 자체의 ApplicationSetting에 두는 편이 낫습니다. UI에서 설정을 관리하는 편이 설정 파일을 관리하는 것보다 대체로 더 나은 사용자 경험입니다. 개발 비용 측면에서는 gitlab.yml을 수정하는 편이 반복 속도가 더 빠른 것처럼 보이는 경우가 많지만, 아래의 모든 배포 방식을 고려하면 좋지 않은 절충일 수 있습니다.
gitlab.yml에 설정을 추가할 때는 다음을 수행합니다.

설정이 함께
Omnibus에 추가되었는지 확인합니다.
필요하면 Charts에 추가되었는지도 확인합니다.
GDK에 추가되었는지도 확인합니다.

유지 관리 작업#
GitLab은 버전 정보를 확인하고 설정이 애플리케이션 내에서 제대로 구성되었는지 빠르게 점검할 수 있는 Rake 태스크를 제공합니다. 유지 관리 Rake 태스크를 참고합니다.
간단히 말해 다음을 실행합니다.
sudo -i -u git
cd gitlab
bundle exec rake gitlab:env:info RAILS_ENV=production
bundle exec rake gitlab:check RAILS_ENV=production

sudo -i -u git 또는 sudo su - git으로
git 사용자로 로그인하는 것을 권장합니다. GitLab이 제공하는 sudo 명령은 Ubuntu에서는 동작하지만,
RHEL에서는 항상 동작하지는 않습니다.
GitLab.com#
GitLab.com 아키텍처는
참고용으로 자세히 설명되어 있지만, 이 아키텍처는 사용자가 수백만 명인 경우에만
유용합니다.
AI 아키텍처#
SaaS 모델 게이트웨이를 통해 AI 네이티브 기능을 사용할 수 있습니다.