GitLab 서버에서 GitLab Mattermost 서비스를 실행할 수 있습니다. Mattermost는 GitLab의 단일 애플리케이션의 일부가 아닙니다. Mattermost와 GitLab 간에는 좋은 통합이 있으며, Linux 패키지를 통해 설치할 수 있습니다. 그러나 Mattermost는 별도의 회사의 별도 애플리케이션입니다. GitLab 지원팀은 GitLab과의 통합 외에 Mattermost 관련 질문에 대한 도움을 제공할 수 없습니다. Mattermost 자체에 대한 도움이 필요하면 커뮤니티 지원 리소스를 참조하세요.

사전 요구 사항#

GitLab Mattermost의 각 릴리스는 Linux용 AMD 64 칩셋에서 컴파일되고 수동으로 테스트됩니다. Raspberry Pi와 같은 ARM 칩셋 및 운영 체제는 지원되지 않습니다.

시작하기#

GitLab Mattermost는 자체 가상 호스트에서 실행되어야 합니다. DNS 설정에서 동일한 머신을 가리키는 두 개의 항목이 필요합니다. 예: gitlab.example.com과 mattermost.example.com.

GitLab Mattermost는 기본적으로 비활성화되어 있습니다. 활성화하려면:

1. /etc/gitlab/gitlab.rb를 편집하고 Mattermost 외부 URL을 추가하세요:

   mattermost_external_url 'https://mattermost.example.com'
   

2. GitLab을 재구성하세요:

   sudo gitlab-ctl reconfigure
   

3. GitLab Mattermost가 https://mattermost.example.com에서 접근 가능하고 GitLab에 연결하도록 인증되어 있는지 확인하세요. GitLab으로 Mattermost를 인증하면 사용자가 GitLab을 SSO 공급자로 사용할 수 있습니다.

Linux 패키지는 애플리케이션이 동일한 서버에서 실행 중인 경우 GitLab으로 GitLab Mattermost를 자동으로 인증하려고 합니다.

자동 인증에는 GitLab 데이터베이스에 대한 액세스가 필요합니다. GitLab 데이터베이스를 사용할 수 없는 경우 GitLab Mattermost 인증 섹션에 설명된 프로세스를 사용하여 GitLab에 대한 액세스를 위해 GitLab Mattermost를 수동으로 인증해야 합니다.

Mattermost 구성#

Mattermost System Console을 사용하여 Mattermost를 구성할 수 있습니다. Mattermost 설정과 설정 위치의 광범위한 목록은 Mattermost 문서에서 확인할 수 있습니다.

System Console 사용이 권장되지만 다음 옵션 중 하나를 사용하여 Mattermost를 구성할 수도 있습니다:

1. /var/opt/gitlab/mattermost/config.json을 통해 Mattermost 구성을 직접 편집하세요.
2. gitlab.rb에서 mattermost['env'] 설정을 변경하여 Mattermost 실행에 사용되는 환경 변수를 지정하세요. 이 방법으로 구성된 설정은 System Console에서 비활성화되며 Mattermost를 재시작하지 않고는 변경할 수 없습니다.

HTTPS로 GitLab Mattermost 실행#

SSL 인증서와 SSL 인증서 키를 /etc/gitlab/ssl에 넣으세요. 디렉토리가 없으면 만드세요:

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp mattermost.gitlab.example.key mattermost.gitlab.example.crt /etc/gitlab/ssl/

/etc/gitlab/gitlab.rb에서 다음 구성을 지정하세요:

mattermost_external_url 'https://mattermost.gitlab.example'
mattermost_nginx['redirect_http_to_https'] = true

인증서와 키의 이름이 mattermost.gitlab.example.crt와 mattermost.gitlab.example.key가 아닌 경우, 다음 전체 경로도 추가해야 합니다:

mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt"
mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key"

여기서 mattermost-nginx.crt는 SSL 인증서이고 mattermost-nginx.key는 SSL 키입니다.

구성이 설정되면 sudo gitlab-ctl reconfigure를 실행하여 변경 사항을 적용하세요.

외부 PostgreSQL 서비스로 GitLab Mattermost 실행#

기본적으로 Mattermost는 Linux 패키지에 번들된 PostgreSQL 서비스를 사용합니다. 외부 PostgreSQL 서비스와 함께 Mattermost를 사용하려면 자체 특정 구성이 필요합니다. GitLab에서 사용하는 기존 외부 PostgreSQL 연결 구성은 Mattermost에 자동으로 상속되지 않습니다.

1. /etc/gitlab/gitlab.rb를 편집하고 다음 구성을 지정하세요:

   mattermost['sql_driver_name'] = 'postgres'
   mattermost['sql_data_source'] = "user=gitlab_mattermost host=<hostname-of-postgresql-service> port=5432 sslmode=required dbname=<mattermost_production> password=<user-password>"
   

2. mattermost['sql_data_source']에 정의한 user 값과 password 값에 맞는 PostgreSQL 사용자를 만드세요.

3. 사용된 dbname 값에 맞는 PostgreSQL 데이터베이스를 만드세요.

4. user에게 dbname으로 만든 데이터베이스에 대한 권한이 있는지 확인하세요.

5. GitLab을 재구성하고 Mattermost를 재시작하여 변경 사항을 적용하세요:

   sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart mattermost
   

별도의 서버에서 GitLab Mattermost 실행#

GitLab과 GitLab Mattermost를 두 개의 별도 서버에서 실행하는 경우 GitLab 서비스는 여전히 GitLab Mattermost 서버에 설정됩니다. 그러나 GitLab 서비스는 사용자 요청을 수락하거나 시스템 리소스를 소비하지 않습니다. GitLab Mattermost 서버에서 다음 설정과 구성 세부 정보를 사용하여 Linux 패키지에 번들된 GitLab 서비스를 효과적으로 비활성화할 수 있습니다.

mattermost_external_url 'http://mattermost.example.com'

# Mattermost 서버에서 GitLab 서비스 종료
alertmanager['enable'] = false
gitlab_exporter['enable'] = false
gitlab_kas['enable'] = false
gitlab_rails['enable'] = false
grafana['enable'] = false
letsencrypt['enable'] = false
node_exporter['enable'] = false
postgres_exporter['enable'] = false
prometheus['enable'] = false
redis_exporter['enable'] = false
redis['enable'] = false

그런 다음 GitLab Mattermost 인증 섹션의 적절한 단계를 따르세요. 마지막으로, GitLab과의 통합을 활성화하려면 GitLab 서버에 다음을 추가하세요:

gitlab_rails['mattermost_host'] = "https://mattermost.example.com"

기본적으로 GitLab Mattermost는 모든 사용자가 GitLab으로 가입하도록 요구하며 이메일로 가입 옵션을 비활성화합니다. GitLab SSO에 관한 Mattermost 문서를 참조하세요.

GitLab Mattermost를 GitLab으로 수동으로 (재)인증#

GitLab Mattermost 재인증#

GitLab Mattermost를 재인증하려면 먼저 기존 인증을 취소해야 합니다. GitLab의 설정 > 애플리케이션 영역에서 이를 수행할 수 있습니다. 그런 다음 다음 섹션의 단계를 따라 인증을 완료하세요.

GitLab Mattermost 인증#

GitLab의 설정 > 애플리케이션 영역으로 이동하세요. 새 애플리케이션을 만들고 리다이렉트 URI에 다음을 사용하세요 (HTTPS를 사용하는 경우 http를 https로 교체하세요):

http://mattermost.example.com/signup/gitlab/complete
http://mattermost.example.com/login/gitlab/complete

신뢰할 수 있음 및 기밀 설정을 선택하세요. 범위 아래에서 read_user를 선택하세요. 그런 다음 애플리케이션 저장을 선택하세요.

애플리케이션이 생성되면 Application ID와 Secret이 제공됩니다. 필요한 또 다른 정보는 GitLab 인스턴스의 URL입니다. GitLab Mattermost를 실행하는 서버로 돌아가서 이전에 받은 값을 사용하여 다음과 같이 /etc/gitlab/gitlab.rb 구성 파일을 편집하세요:

mattermost['gitlab_enable'] = true
mattermost['gitlab_id'] = "12345656"
mattermost['gitlab_secret'] = "123456789"
mattermost['gitlab_scope'] = "read_user"
mattermost['gitlab_auth_endpoint'] = "http://gitlab.example.com/oauth/authorize"
mattermost['gitlab_token_endpoint'] = "http://gitlab.example.com/oauth/token"
mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user"

변경 사항을 저장한 다음 sudo gitlab-ctl reconfigure를 실행하세요. 오류가 없으면 GitLab과 GitLab Mattermost가 올바르게 구성된 것입니다.

숫자 사용자 및 그룹 식별자 지정#

Linux 패키지는 mattermost 사용자와 그룹을 만듭니다. 다음과 같이 /etc/gitlab/gitlab.rb에서 이러한 사용자의 숫자 식별자를 지정할 수 있습니다:

mattermost['uid'] = 1234
mattermost['gid'] = 1234

sudo gitlab-ctl reconfigure를 실행하여 변경 사항을 적용하세요.

사용자 지정 환경 변수 설정#

필요한 경우 /etc/gitlab/gitlab.rb를 통해 Mattermost에서 사용할 사용자 지정 환경 변수를 설정할 수 있습니다. 이는 Mattermost 서버가 회사 인터넷 프록시 뒤에서 운영되는 경우 유용할 수 있습니다. /etc/gitlab/gitlab.rb에서 해시 값과 함께 mattermost['env']를 제공하세요. 예:

mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "NO_PROXY" => "my_no_proxy"}

sudo gitlab-ctl reconfigure를 실행하여 변경 사항을 적용하세요.

번들된 PostgreSQL 데이터베이스에 연결#

번들된 PostgreSQL 데이터베이스에 연결해야 하고 기본 Linux 패키지 데이터베이스 구성을 사용 중인 경우 PostgreSQL 슈퍼유저로 연결할 수 있습니다:

sudo gitlab-psql -d mattermost_production

GitLab Mattermost 백업#

GitLab Mattermost는 일반 Linux 패키지 백업 Rake 작업에 포함되지 않습니다.

일반 Mattermost 백업 및 재해 복구 문서를 백업해야 할 항목에 대한 가이드로 사용할 수 있습니다.

번들된 PostgreSQL 데이터베이스 백업#

번들된 PostgreSQL 데이터베이스를 백업해야 하고 기본 Linux 패키지 데이터베이스 구성을 사용 중인 경우 다음 명령을 사용하여 백업할 수 있습니다:

sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz

data 디렉토리 및 config.json 백업#

Mattermost에는 data 디렉토리와 config.json 파일이 있어 함께 백업해야 합니다:

sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json

GitLab Mattermost 복원#

이전에 GitLab Mattermost의 백업을 만든 경우 다음 명령을 실행하여 복원할 수 있습니다:

# 열린 데이터베이스 연결이 없도록 Mattermost 중지
sudo gitlab-ctl stop mattermost

# Mattermost 데이터베이스 삭제
sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Mattermost 데이터베이스 생성
sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# 데이터베이스 복원 수행
# /tmp/mattermost_dbdump_2021-08-05.sql.gz를 백업 파일로 교체하세요
sudo -u mattermost sh -c "zcat /tmp/mattermost_dbdump_2021-08-05.sql.gz | /opt/gitlab/embedded/bin/psql -U gitlab_mattermost -h /var/opt/gitlab/postgresql -p 5432 mattermost_production"

# 데이터 디렉토리 및 config.json 복원
# /tmp/mattermost_data_2021-08-09.gz를 백업 파일로 교체하세요
sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost

# 필요한 경우 권한 수정
sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data
sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json

# Mattermost 시작
sudo gitlab-ctl start mattermost

Mattermost 명령줄 도구 (CLI)#

mmctl은 Mattermost 서버용 CLI 도구로 로컬에 설치되어 Mattermost API를 사용하며, 원격으로도 사용할 수 있습니다. 로컬 연결을 위해 Mattermost를 구성하거나 로컬 로그인 자격 증명(GitLab SSO를 통하지 않고)을 사용하여 관리자로 인증해야 합니다. 실행 파일은 /opt/gitlab/embedded/bin/mmctl에 있습니다.

로컬 연결을 통한 mmctl 사용#

로컬 연결의 경우 mmctl 바이너리와 Mattermost는 동일한 서버에서 실행해야 합니다. 로컬 소켓을 활성화하려면:

1. /var/opt/gitlab/mattermost/config.json을 편집하고 다음 줄을 추가하세요:

   {
       "ServiceSettings": {
          ...
           "EnableLocalMode": true,
           "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket",
           ...
       }
   }
   

2. Mattermost를 재시작하세요:

   sudo gitlab-ctl restart mattermost
   

그런 다음 sudo /opt/gitlab/embedded/bin/mmctl --local을 사용하여 Mattermost 인스턴스에서 mmctl 명령을 실행할 수 있습니다.

예를 들어, 사용자 목록을 표시하려면:

$ sudo /opt/gitlab/embedded/bin/mmctl --local user list

13dzo5bmg7fu8rdox347hbfxde: appsbot (appsbot@localhost)
tbnkwjdug3dejcoddboo4yuomr: boards (boards@localhost)
wd3g5zpepjgbfjgpdjaas7yj6a: feedbackbot (feedbackbot@localhost)
8d3zzgpurp85zgf1q88pef73eo: playbooks (playbooks@localhost)
There are 4 users on local instance

원격 연결을 통한 mmctl 사용#

원격 연결이나 소켓을 사용할 수 없는 로컬 연결의 경우, SSO가 아닌 사용자를 만들고 해당 사용자에게 관리자 권한을 부여하세요. 그런 다음 해당 자격 증명을 사용하여 mmctl을 인증할 수 있습니다:

$ /opt/gitlab/embedded/bin/mmctl auth login http://mattermost.example.com

Connection name: test
Username: local-user
Password:
 credentials for "test": "local-user@http://mattermost.example.com" stored

GitLab 및 Mattermost 통합 구성#

플러그인을 사용하여 이슈, 병합 요청, 풀 리퀘스트에 대한 알림과 병합 요청 리뷰, 읽지 않은 메시지, 작업 할당에 대한 개인 알림을 받도록 Mattermost를 구독할 수 있습니다. 이슈 생성 및 보기나 배포 트리거와 같은 작업을 수행하는 슬래시 명령을 사용하려면 GitLab Mattermost 슬래시 명령을 사용하세요.

플러그인과 슬래시 명령은 함께 또는 개별적으로 사용할 수 있습니다.

이메일 알림#

GitLab Mattermost용 SMTP 설정#

이러한 설정은 시스템 관리자가 Mattermost System Console을 통해 구성합니다. System Console의 환경 > SMTP 탭에서 SMTP 공급자가 제공하는 SMTP 자격 증명이나 sendmail을 사용하기 위해 127.0.0.1과 포트 25를 입력할 수 있습니다. 필요한 특정 설정에 대한 자세한 내용은 Mattermost 문서에서 확인할 수 있습니다.

이러한 설정은 /var/opt/gitlab/mattermost/config.json에서도 구성할 수 있습니다.

이메일 일괄 처리#

이 기능을 활성화하면 사용자가 이메일 알림을 받는 빈도를 제어할 수 있습니다.

이메일 일괄 처리는 Mattermost System Console에서 환경 > SMTP 탭으로 이동하고 이메일 일괄 처리 사용 설정을 True로 설정하여 활성화할 수 있습니다.

이 설정은 /var/opt/gitlab/mattermost/config.json에서도 구성할 수 있습니다.

GitLab Mattermost 업그레이드#

GitLab Mattermost는 일반 Linux 패키지 업데이트 프로세스를 통해 업그레이드할 수 있습니다. 이전 버전의 GitLab을 업그레이드할 때 GitLab 외부에서 Mattermost 구성 설정이 변경되지 않은 경우에만 업데이트 프로세스를 사용할 수 있습니다. 즉, System Console을 통해서도 config.json에 직접 변경 사항이 없어야 합니다.

gitlab.rb만 사용하여 Mattermost를 구성한 경우 Linux 패키지를 사용하여 GitLab을 업그레이드한 다음 gitlab-ctl reconfigure를 실행하여 GitLab Mattermost를 최신 버전으로 업그레이드할 수 있습니다.

그렇지 않은 경우 두 가지 옵션이 있습니다:

1. config.json에 적용된 변경 사항으로 gitlab.rb를 업데이트하세요. 모든 config.json 설정이 gitlab.rb에서 사용 가능하지 않기 때문에 일부 매개변수를 추가해야 할 수도 있습니다. 완료되면 Linux 패키지가 GitLab Mattermost를 한 버전에서 다음 버전으로 업그레이드할 수 있어야 합니다.
2. Mattermost를 Linux 패키지가 제어하는 디렉토리 외부로 마이그레이션하여 독립적으로 관리하고 업그레이드할 수 있습니다. Mattermost 마이그레이션 가이드를 따라 Mattermost 구성 설정과 데이터를 Linux 패키지와 독립적인 다른 디렉토리 또는 서버로 이동하세요.

이전 버전에 대한 전체 업그레이드 주의 사항 및 특별 고려 사항 목록은 Mattermost 문서를 참조하세요.

Linux 패키지와 함께 제공되는 GitLab Mattermost 버전 및 에디션 (deprecated)#

다음 표는 GitLab 15.0 이상에서의 Mattermost 버전 변경 사항을 보여줍니다:

Linux 패키지는 무료 오픈 소스 에디션이며 상업적 기능을 포함하지 않는 Mattermost Team Edition을 번들로 제공합니다. Mattermost Enterprise Edition으로 업그레이드하려면 Mattermost의 업그레이드 문서를 참조하세요.

OAuth 2.0 시퀀스 다이어그램#

다음 이미지는 GitLab이 Mattermost의 OAuth 2.0 공급자로 작동하는 방법에 대한 시퀀스 다이어그램입니다. 통합이 작동하도록 하는 오류를 해결하는 데 사용할 수 있습니다:

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
accTitle: GitLab as OAuth 2.0 provider
accDescr: Sequence of actions that happen when a user authenticates to GitLab through Mattermost.
User->>Mattermost: GET https://mm.domain.com
Note over Mattermost, GitLab: Obtain access code
Mattermost->>GitLab: GET https://gitlab.domain.com/oauth/authorize
Note over User, GitLab: GitLab user signs in (if necessary)
Note over GitLab: GitLab verifies client_id matches an OAuth application
GitLab->>User: GitLab asks user to authorize Mattermost OAuth app
User->>GitLab: User selects 'Allow'
Note over GitLab: GitLab verifies redirect_uri matches list of valid URLs
GitLab->>User: 302 redirect: https://mm.domain.com/signup/gitlab/complete
User->>Mattermost: GET https://mm.domain.com/signup/gitlab/complete
Note over Mattermost, GitLab: Exchange access code for access token
Mattermost->>GitLab: POST http://gitlab.domain.com/oauth/token
GitLab->>GitLab: Doorkeeper::TokensController#35;create
GitLab->>Mattermost: Access token
Note over Mattermost, GitLab: Mattermost looks up GitLab user
Mattermost->>GitLab: GET https://gitlab.domain.com/api/v4/user
GitLab->>Mattermost: User details
Mattermost-&gt;&gt;User: Mattermost/GitLab user ready</code></pre></details></div>

커뮤니티 지원 리소스#
GitLab Mattermost 배포에 대한 도움과 지원은 다음을 참조하세요:

Mattermost 이슈 문제 해결
Mattermost 포럼