로컬 개발용 Slack의 GitLab Duo 설정
GitLab v19.6요약
Slack의 GitLab Duo는 사용자가 Slack 채널이나 스레드에서 GitLab 봇을 멘션하면 응답합니다. 이 기능을 로컬에서 테스트하려면 다음을 수행해야 합니다. GitLab Duo가 설정된 GDK가 있어야 합니다.
Slack의 GitLab Duo는 사용자가 Slack 채널이나 스레드에서 GitLab 봇을 멘션하면 응답합니다. 이것이 동작하려면 Slack이 인터넷을 통해 GDK에 접근할 수 있어야 합니다.
이 기능을 로컬에서 테스트하려면 다음을 수행해야 합니다.
- 터널을 통해 GDK를 인터넷에 노출합니다.
- GitLab for Slack 앱의 사본을 직접 만들고, 요청 URL이 터널을 가리키게 합니다.
- GitLab이 Slack을 호출할 때 사용할 봇 토큰을 갖도록 GitLab에서 앱을 설치합니다.
사전 요구 사항#
-
GitLab Duo가 설정된 GDK가 있어야 합니다.
-
gitlab--duo태그가 지정되고 GDK에 등록된 CI/CD 러너가 있어야 합니다.dockerexecutor를 사용합니다. 플로는 Docker 이미지에서 실행되므로shellexecutor는 동작하지 않습니다. 자세한 내용은 플로를 실행하도록 러너 구성을 참고합니다. -
관리자인 Slack 워크스페이스가 있어야 합니다. GitLab 워크스페이스가 아니라 Slack 개발자 샌드박스를 사용합니다.
-
실험 및 베타 GitLab Duo 기능이 켜져 있어야 합니다. GDK에서는 인스턴스 수준 설정입니다.
ApplicationSetting.current.update!(instance_level_ai_beta_features_enabled: true) -
사용자에게 기본 GitLab Duo 네임스페이스가 설정되어 있고, 해당 최상위 그룹에서 Developer Flow가 켜져 있어야 합니다. 그룹에
slack_duo_api_flow기능 플래그가 활성화되어 있다면 대신 GitLab Duo for Slack 플로를 켭니다.
Slack 개발자 샌드박스 사용#
일부 Slack 기능은 유료 Slack 요금제에서만 사용할 수 있으며, 무료 워크스페이스에는 알림 없이 이 기능이 없습니다. 개발자 샌드박스는 모든 유료 기능이 활성화된 워크스페이스이므로 테스트 워크스페이스로 사용합니다.
샌드박스를 받으려면 다음을 수행합니다.
- 무료 Slack 개발자 프로그램에 등록합니다.
- 개발자 대시보드에서 Provision Sandbox를 선택합니다.
- 샌드박스 페이지에 표시된 URL에서 샌드박스 워크스페이스를 열고 Slack 개발자 계정으로 로그인합니다.
샌드박스는 약 6개월 후 자동으로 보관 처리되며 무료 요금제에는 월별 프로비저닝 한도가 있으므로, 테스트마다 새로 만들지 말고 샌드박스 하나를 재사용합니다.
GDK를 인터넷에 노출#
Slack이 GDK에 접근할 수 있어야 하므로, GDK에 공개 HTTPS URL을 제공하는 리버스 터널이 필요합니다.
터널은 로컬 머신을 공용 인터넷에 노출합니다. 노트북 방화벽 요구 사항이 로컬 방화벽 우회를 금지하므로 GitLab 팀 구성원은 승인된 예외를 받아야 합니다. 작업을 마치면 터널을 중지합니다. 예시는 이 과거 보안 예외 요청을 참고합니다.
TLS를 종료하고 GDK로 전달하는 터널이면 무엇이든 동작합니다. 다음 단계는
ngrok과 cloudflared를 다룹니다. GitLab 관리형 macOS 기기에서는 ngrok이 차단됩니다. 실행하면
ngrok is not allowed for use at GitLab이라는 대화상자가 나타나고 #it_security_help
Slack 채널을 안내합니다. 관리형 Mac에서는 대신 cloudflared를 사용합니다.
다음 명령에서 gdk.test:8080을 GDK가 수신 대기하는 호스트와 포트로 바꿉니다.
예를 들어 NGINX 없이 GDK를 실행한다면 gdk.test:3000을 사용합니다.
ngrok 사용#
-
ngrok을 설치한 다음ngrok대시보드에서 인증 토큰을 추가합니다.ngrok config add-authtoken <your_token> -
ngrok대시보드의 Domains 페이지에서 고정 도메인을 확보합니다. 무료 요금제에는 하나가 포함되어 있습니다. 고정 도메인을 사용하면 터널 URL이 재시작 후에도 유지되므로 Slack 앱과RAILS_HOSTS를 한 번만 구성하면 됩니다. -
GDK가 수신 대기하는 호스트와 포트로 터널을 시작하고 고정 도메인을 전달합니다.
ngrok http gdk.test:8080 --url=<your_static_domain>.ngrok-free.app
cloudflared 사용#
-
cloudflared를 설치합니다.brew install cloudflared -
GDK가 수신 대기하는 호스트와 포트로 퀵 터널을 시작합니다.
cloudflared tunnel --url "http://gdk.test:8080"이 명령은 무작위
https://<random-words>.trycloudflare.com호스트 이름을 출력합니다. 프로세스를 실행 상태로 둡니다. 중지하면 터널이 닫힙니다.
퀵 터널에는 고정 호스트 이름이 없으므로 재시작할 때마다 새 호스트 이름이 생성됩니다. 새 호스트 이름이 생길 때마다
RAILS_HOSTS와 Slack 앱 매니페스트를 업데이트하고, Slack과 GitLab 양쪽에서 앱을 다시 설치해야 합니다.
안정적인 호스트 이름이 필요하면
Cloudflare 이름 지정 터널을 만듭니다.
이를 만들려면 Cloudflare 계정과 도메인이 필요합니다. GitLab 팀 구성원은 승인 없이
상표가 아닌 도메인 이름을
구매할 수 있습니다.
Rails에서 터널 호스트 허용#
-
RAILS_HOSTS를 터널 호스트 이름으로 설정해 GDK를 시작합니다.RAILS_HOSTS=<your_tunnel_hostname> gdk startRAILS_HOSTS에는 URL이 아니라 호스트 이름만 지정합니다.https://접두사가 있으면 호스트 이름이 일치하지 않아 Rails가 계속 해당 호스트를 차단합니다. -
브라우저에서 터널 URL을 열어 터널이 GDK에 도달하는지 확인합니다. GDK 로그인 페이지가 보여야 합니다(에셋이 로드되지 않아도 괜찮습니다).
Slack 앱 생성#
GITLAB_SIMULATE_SAAS가 설정되어 있으면 Create Slack app 버튼이 나타나지 않습니다.
버튼이 보이지 않으면 해당 변수를 해제하고 GDK를 재시작한 뒤 계속합니다.
-
GDK의 오른쪽 상단에서 Admin을 선택합니다.
-
Settings > General을 선택한 다음 GitLab for Slack app을 확장합니다.
-
Create Slack app을 선택합니다. GitLab이 생성된 매니페스트와 함께 Slack으로 리디렉션합니다.
NGINX에서
502 Bad Gateway페이지가 반환되면 Slack 앱을 만들 때 NGINX가502 Bad Gateway를 반환함을 참고합니다. -
워크스페이스를 선택하고 Next를 선택한 다음 Create and Install을 선택합니다.
-
Review app permissions 페이지에서 Allow를 선택한 다음 Go to App Settings를 선택합니다.
-
GitLab으로 돌아와 GitLab for Slack app 섹션에서 다음을 수행합니다.
- Enable GitLab for Slack app 체크박스를 선택합니다.
- 앱 설정 페이지의 자격 증명 네 가지를 붙여넣습니다.
- Save changes를 선택합니다.
-
Slack에서 Your Apps로 이동해 앱을 선택한 다음 App Manifest를 선택합니다.
-
GDK 호스트(
http://gdk.test:8080)가 나오는 모든 곳을 터널 URL로 바꿉니다. 단, GDK URL 그대로 두어야 하는oauth_config.redirect_urls는 제외합니다. 스킴이http에서https로 바뀌는 점에 유의합니다.[!note] Create Slack app 페이지에서 이 값을 편집하면 Slack이 변경 사항을 무시하므로 동작하지 않습니다. 이는 나중에 수정될 수 있는 버그일 수 있습니다.
-
Save Changes를 선택합니다.
-
Install App으로 이동해 새 매니페스트가 적용되도록 앱을 다시 설치합니다.
GitLab에 봇 토큰 제공#
Slack에서 앱을 설치해도 GitLab은 봇 토큰을 받지 못합니다. SlackIntegration 레코드에 토큰을 저장하는
OAuth 교환을 실행하도록 GitLab에서 앱을 한 번 더 설치합니다.
- 왼쪽 사이드바에서 Settings > Integrations를 선택합니다.
- GitLab for Slack app > Install GitLab for Slack app을 선택합니다.
- Slack에서 테스트 워크스페이스를 선택한 다음 Allow를 선택합니다.
Slack에서 앱을 다시 설치할 때마다 이 단계를 반복합니다. 다시 설치하면 GitLab이 받지 못하는 새 봇 토큰이 발급되기 때문입니다.
멘션 테스트#
- Slack의 채널에서
@GitLab hi처럼 봇을 멘션합니다. 봇이 채널에 없으면 Slack이 봇을 추가하라는 안내로 응답합니다. Add them을 선택합니다. Slack은 안내를 일으킨 멘션을 전달하지 않으므로 봇을 다시 멘션합니다. - Slack 계정이 GitLab 사용자와 연결되어 있지 않으면 봇이 잠금 반응(🔒)을 추가하고 인가 링크가 포함된 임시 메시지를 보냅니다. 링크를 선택하고 인가한 다음 봇을 다시 멘션합니다.
- 봇이 메시지에 반응하고, Developer Flow를 CI/CD 워크로드로 실행하며,
GitLab의 세션 링크와 함께 스레드에 답글을 남깁니다.
slack_duo_api_flow기능 플래그가 활성화되어 있으면 봇은 대신 CI/CD 러너 없이 GitLab Duo for Slack 플로를 실행합니다.
첫 멘션은 기본 GitLab Duo 네임스페이스에서 프로젝트를 만들 수 있는 사용자로 실행합니다. Slack
멘션에는 프로젝트 컨텍스트가 없으므로 Ai::Messaging::DefaultProjectFlowResolver가
기본 GitLab Duo 네임스페이스에서 프로젝트를 도출하고 Ai::Messaging::WorkspaceProjectService를 호출하며,
이 서비스가 해당 네임스페이스에서 duo-workspace 프로젝트를 찾거나 새로 만듭니다.
Slack 워크스페이스의 GitLab Duo 그룹 테스트#
slack_duo_group 기능 플래그를 사용하면 Slack 워크스페이스의 모든 세션이 하나의
최상위 그룹, 즉 워크스페이스의 GitLab Duo 그룹에서 실행됩니다.
세션은 더 이상 사용자의 기본 GitLab Duo 네임스페이스에서 실행되지 않습니다.
사용자 대상 동작은
GitLab Duo가 실행되는 위치 선택을 참고합니다.
테스트하려면 다음을 수행합니다.
-
인스턴스에서 기능 플래그를 활성화합니다. 이 플래그는 최상위 그룹별로 롤아웃되지만 GitLab Duo 그룹이 없는 워크스페이스는 인스턴스를 따릅니다.
Feature.enable(:slack_duo_group) -
GitLab에 봇 토큰 제공과 같은 방식으로, 단 그룹 설정에서 소유한 최상위 그룹에 앱을 설치합니다. 워크스페이스에서 처음 설치한 최상위 그룹이 해당 워크스페이스의 GitLab Duo 그룹이 됩니다. 확인하려면 Rails 콘솔에서 다음을 실행합니다.
Integrations::SlackWorkspace::Workspace.for_team('<team_id>')&.duo_namespace -
그룹에서 GitLab Duo, GitLab Duo Agent Platform, 실험 및 베타 기능을 켭니다.
-
봇을 멘션합니다. 세션은 그룹에서 Workhorse로 GitLab Duo for Slack 플로와 함께 실행됩니다. CI/CD 러너가 필요하지 않으며
duo-workspace프로젝트도 만들지 않습니다.
GitLab Duo를 끄거나 다시 켜려면 그룹의 GitLab for Slack 앱 설정에서 GitLab Duo 섹션을 사용합니다. 인스턴스용으로 설치한 워크스페이스에서는 Admin 영역을 사용합니다.
모든 상태의 여러 그룹, 프로젝트, Slack 워크스페이스를 한 번에 설정하려면 구현 이슈의 시드 스크립트를 사용합니다.
코드에서 확인할 위치는 다음과 같습니다.
EE::Integrations::SlackEvents::AppMentionedService#duo_group_path?가 멘션이 이 경로를 따를지 결정하고,Integrations::SlackWorkspace::DuoMentionExecutionContainerResolver가 그룹을 찾습니다.Integrations::SlackWorkspace::EnableDuoGroupService,DisableDuoGroupService,ReleaseDuoGroupService,ChangeDuoGroupService가slack_workspaces테이블에 기록합니다.Integrations::SlackWorkspace::DuoGroupEligibility가 그룹이 워크스페이스에서 GitLab Duo를 실행할 수 있는지 결정합니다. 또한 누가 결정하는지도 알려 줍니다. 그룹의 Owner이거나, 인스턴스 설치의 경우 관리자입니다.
로컬 설정 초기화#
처음부터 다시 시작하려면 GDK에서 모든 Slack 통합 데이터를 제거하고 Slack에서 앱을 삭제합니다.
-
Rails 콘솔에서 다음을 실행합니다.
Integrations::SlackWorkspace::Workspace.delete_all SlackIntegration.delete_all Integrations::GitlabSlackApplication.delete_all ChatName.delete_all ApplicationSetting.current.update!( slack_app_enabled: false, slack_app_id: nil, slack_app_secret: nil, slack_app_signing_secret: nil, slack_app_verification_token: nil ) -
Slack의 Your Apps로 이동해 앱을 열고 삭제합니다.
문제 해결#
Slack이 GDK에 접근할 수 있는지 확인#
- Slack에서 Your Apps로 이동해 앱을 선택합니다.
- Event Subscriptions를 선택합니다. 요청 URL 옆에서 Retry 또는 Verify를 선택합니다. Slack이 GDK에 챌린지 요청을 보내며, 녹색 확인 표시가 나타나면 터널이 동작하는 것입니다.
나중에 범위를 추가하도록 매니페스트를 변경한다면 Install App > Reinstall to Workspace를 선택합니다. Slack은 설치 시점에만 범위를 부여하므로 새 범위는 다시 설치한 후에만 적용됩니다.
Slack 앱을 만들 때 NGINX가 502 Bad Gateway를 반환함#
Create Slack app은 전체 앱 매니페스트를 URL 인코딩해 Location 헤더에 담아 Slack으로
리디렉션합니다. 이 헤더가 GDK NGINX 구성의 기본 프록시 버퍼보다 크므로 NGINX가
응답을 거부하고 log/nginx/current에 upstream sent too big header while reading response header from upstream을 기록합니다.
이 오류를 해결하려면 GDK 디렉터리의 nginx/conf/nginx.conf에서 server 블록의
다른 proxy_ 설정 옆에 다음을 추가합니다.
proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;
그런 다음 gdk restart nginx를 실행합니다. 이 파일은 components/nginx/nginx.conf.erb에서 생성되므로
gdk reconfigure가 변경 사항을 덮어씁니다. 변경 사항을 유지하려면 템플릿에도 같은 변경을 적용합니다.
Slack API가 account_inactive를 반환함#
integrations_json.log에 "error": "account_inactive"가 있는 Slack API 오류가 기록되고, 봇이
반응하거나 답글을 남기지 않습니다. Slack은 멘션을 받았고 GitLab도 이를 처리했지만, GitLab이
해지된 봇 토큰을 가지고 있어 Slack으로 되돌리는 모든 호출이 실패합니다.
이 오류를 해결하려면 GitLab에 현재 토큰을 다시 제공합니다.
- Admin > Settings > Integrations > GitLab for Slack app으로 이동해 휴지통 아이콘을 선택하여 통합을 삭제합니다.
- Install GitLab for Slack app을 선택한 다음 Allow를 선택합니다.
GitLab Duo @mention 실패#
봇이 스레드에 오류를 게시하면 해당 메시지를
GitLab Duo @mention 실패에서
찾아 대조합니다. 이 페이지에는 각 메시지, 원인, 해결 방법이 나와 있습니다. 또한 log/integrations_json.log와 log/sidekiq.log에서
필터링할 로그 필드도 설명합니다.
로컬 개발에서는 두 가지 경우가 다르게 동작합니다.
- 봇이 아무것도 게시하지 않습니다. 터널에 문제가 있다고 가정하기 전에 멘션이 GDK에 도달했는지 확인합니다.
Slack 요청은 터널과 NGINX를 거쳐 GDK에 도달하므로, 전달된 멘션은 GDK 디렉터리의
nginx/logs/access.log에Slackbot의POST /api/v4/integrations/slack/events로 나타나고,log/integrations_json.log의meta.remote_ip에는 Slack의 IP 주소가 나타납니다. 두 로그 어디에도 멘션이 기록되지 않았다면 Slack이 GDK에 접근하지 못한 것입니다. 터널이 실행 중인지와RAILS_HOSTS에 터널 호스트가 포함되어 있는지 확인한 다음 Slack에서 요청 URL을 다시 검증합니다. 로그에 기록되어 있다면 멘션은 도착했고 실패는account_inactive처럼 응답 단계에 있는 것입니다. - 봇이
Could not set up the service account for the flow를 게시합니다. 최상위 그룹에서 플로가 꺼져 있을 수 있습니다. 그룹에서 Settings > GitLab Duo로 이동해 Change configuration을 선택하고 Flow execution에서 Developer Flow를 켭니다. 그룹에slack_duo_api_flow기능 플래그가 활성화되어 있다면 대신 GitLab Duo for Slack 플로를 켭니다.
기본 Duo 네임스페이스 프로젝트가 제대로 초기화되지 않음#
Ai::Messaging::WorkspaceProjectService는 initialize_with_readme: true로 프로젝트를 만들므로
리포지터리의 기본 브랜치에 README.md 커밋이 있습니다.
리포지터리가 올바르게 초기화되지 않으면 플로에 체크아웃할 기본 브랜치가 없어 실패합니다. 이 경우 커밋으로 리포지터리를 초기화합니다.