3 min read

Slack 연동 온보딩 가이드

새 프로젝트를 GIIP의 대화형 Slack 봇(giipclaude)과 연결하는 전체 절차를 7단계로 안내합니다. 각 단계를 순서대로 따라가면 끝에서 Slack 채널에 @giipclaude를 멘션해 giip issue를 등록/조회할 수 있게 됩니다.

1. 프로젝트(csn) 확인

Slack 봇을 연결하려면 먼저 이 봇이 속할 GIIP 프로젝트(csn)가 있어야 합니다. 이미 가입/온보딩된 회사가 있다면 이 단계는 건너뛰고 2단계로 이동하세요. 신규 가입이 필요하면:

➡️ 회원가입 가이드 를 먼저 진행하세요.

다음 단계: 2. 서비스 그룹 생성

2. 서비스 그룹 생성

GIIP에서 SK(Secret Key)는 "서비스 그룹" 단위로 발급됩니다. 아직 이 Slack 봇 전용 그룹이 없다면 새로 만드세요.

프로젝트 그룹 목록 페이지로 이동합니다.
[+ 그룹 추가] 버튼으로 새 그룹을 만듭니다(예: slack-bot처럼 용도를 알 수 있는 이름 권장).

다음 단계: 3. SK(Secret Key) 발급

3. SK(Secret Key) 발급

같은 프로젝트 그룹 목록 페이지에서, 방금 만든(또는 기존) 그룹 옆의 [Generate Secret Key] 버튼을 클릭합니다. 발급된 SK 문자열을 안전한 곳에 복사해 두세요 — 7단계에서 그대로 사용합니다.

다음 단계: 4. giip-fde-agent 로컬 설치

4. giip-fde-agent 로컬 설치

Slack 봇은 여러분의 PC(또는 봇을 상시 띄워둘 서버)에서 로컬로 실행됩니다. 정본 템플릿 저장소를 클론해서 설치하세요.

git clone https://github.com/LowyShin/giip-fde-agent.git
cd giip-fde-agent/slack-bot
npm install

다음 단계: 5. Slack App 생성 및 연동

5. Slack App 생성 및 연동

slack-bot/SLACK_APP_SETUP.md(저장소 안에 이미 있음)의 전체 절차를 따르세요. 핵심만 요약하면:

api.slack.com/apps → Create New App → From scratch
OAuth & Permissions → Bot Token Scopes 추가: chat:write, app_mentions:read, channels:history, channels:read, groups:history, groups:read, im:history, im:read, im:write (선택: users:read)
Socket Mode 활성화 → App-Level Token 발급(connections:write 스코프) → xapp-... 복사
Event Subscriptions 활성화 → app_mention, message.im, message.channels, message.groups 구독
Install to Workspace → Bot User OAuth Token(xoxb-...) 복사
slack-bot/.env.example을 .env로 복사하고 SLACK_BOT_TOKEN(xoxb-), SLACK_APP_TOKEN(xapp-), WORKSPACE_DIR 채우기
node index.js(또는 pm2 start index.js --name giipclaude-bot)로 실행

문제가 생기면 SLACK_APP_SETUP.md 하단 "Troubleshooting" 표를 먼저 확인하세요.

다음 단계: 6. Slack 채널 준비

6. Slack 채널 준비

봇이 응답할 Slack 채널을 만들거나 기존 채널을 정합니다.
그 채널에서 /invite @<봇 이름>으로 봇을 초대합니다.
채널 ID를 확인합니다: 채널명 우클릭 → 채널 세부 정보 보기 → 하단의 C0XXXXXXXXX 형식 ID.

다음 단계: 7. GIIP 연동 마무리

7. GIIP 연동 마무리

봇이 Slack에서 살아있는 것을 확인했으면, 이제 그 채널을 3단계에서 발급받은 SK/csn과 연결합니다. 봇에게 DM으로(또는 연결할 채널에서) 아래 명령을 순서대로 입력하세요.

giip account set <login_id> <SK> <csn>
giip channel set <프로젝트명> <채널ID>
giip project set <프로젝트명> <csn>

<login_id>: 이 계정으로 식별될 이메일 등(표시용, 예: you@example.com)
<SK>: 3단계에서 발급받은 값
<csn>: 1단계에서 확인한 프로젝트 번호
<프로젝트명>: 자유롭게 정하는 소문자 식별자(giip issue 등록 시 이 이름으로 라우팅됨)

명령이 모두 성공하면 그 채널에서 @<봇 이름> issue 등록 <내용>처럼 말해서 바로 giip issue를 등록할 수 있습니다.

⚠️ 신규 프로젝트라면: giip project set이 자동으로 봇의 DB 접근 권한(tUserPerCorp)을 부여하려 시도하는데, 완전히 새로운 csn은 보안 게이트로 이 자동 부여가 실패합니다(의도된 동작). 이 경우 명령 응답에 경고가 뜨고, 자동으로 후속 조치 giip issue가 csn 47에 등록됩니다 — GIIP 관리자가 그 이슈를 보고 giipdb/data/seed_tUserPerCorp_botuser.sql에 한 줄을 추가해 수동으로 권한을 부여해야 완전히 연동됩니다. 이 단계만 관리자 개입이 필요하고, 나머지는 전부 셀프서비스입니다.

다음 단계: 연동 후 받게 되는 알림

연동 후 받게 되는 알림

연동이 끝나면 이슈에 코멘트가 달릴 때마다 그 프로젝트(csn)의 Slack 채널로 알림이 전송됩니다. 사람이 웹 화면에서 남긴 코멘트든 봇이 남긴 코멘트든 똑같이 전송됩니다.

알림 설정이 켜져 있어야 받습니다: 프로젝트별 알림 설정이 활성화돼 있는 경우에만 전송됩니다. 설정이 없거나 꺼져 있으면 알림이 오지 않으며, 이것은 오류가 아니라 정상 동작입니다. 활성화는 GIIP 관리자가 합니다.
도착까지 보통 1~2분 걸립니다: 즉시 전송되지 않습니다. 코멘트가 등록되면 먼저 알림 대기열에 쌓이고, 전송 프로세스가 2분 주기로 꺼내어 보냅니다. 실제로 측정한 도착 시간은 11초에서 100초 사이였습니다.
새 이슈 알림과는 별개입니다: 새 이슈가 등록될 때 가는 알림은 전송 경로가 따로 있고(5분 주기) 도착하는 채널도 코멘트 알림과 다를 수 있습니다. 한쪽이 온다고 다른 쪽도 온다고 볼 수 없습니다.

⚠️ 알림이 오지 않으면: 먼저 2분 이상 기다렸는지 확인하세요 — 위에 적은 2분 주기 때문에 코멘트를 달자마자 오지 않는 것은 정상입니다. 그다음 그 프로젝트의 알림 설정이 켜져 있는지 확인하세요. 두 가지 모두 해당하지 않는데도 알림이 오지 않으면 GIIP 관리자에게 문의하세요.

버전: 2.1 (연동 후 받게 되는 알림 안내 추가) 최종 업데이트: 2026-10-22 소스 파일: giipv3/public/help/slack-bot-setup.ko.md

← PreviousMQE Notification Settings Next →MQE Technical Spec