4 min read

Slack Integration Onboarding Guide

A 7-step walkthrough for connecting a new project to GIIP's conversational Slack bot (giipclaude). Follow the steps in order and by the end you'll be able to mention @giipclaude in a Slack channel to register or look up giip issues.

Confirm your project (csn)
Create a service group
Issue an SK (Secret Key)
Install giip-fde-agent locally
Create and connect a Slack App
Prepare a Slack channel
Finish the GIIP linking

1. Confirm your project (csn)

Before you can connect a Slack bot, you need a GIIP project (csn) for it to belong to. If your company is already signed up and onboarded, skip this step and go to step 2. If you need to sign up first:

➡️ Go through the Sign-up Guide first.

Next: 2. Create a service group

2. Create a service group

In GIIP, an SK (Secret Key) is issued per "service group". If you don't have a group dedicated to this Slack bot yet, create one.

Go to the Project Group List page.
Click [+ Add Group] to create a new group (a purpose-revealing name like slack-bot is recommended).

Next: 3. Issue an SK (Secret Key)

3. Issue an SK (Secret Key)

On the same Project Group List page, click [Generate Secret Key] next to the group you just created (or an existing one). Copy the issued SK string somewhere safe — you'll use it as-is in step 7.

Next: 4. Install giip-fde-agent locally

4. Install giip-fde-agent locally

The Slack bot runs locally on your PC (or on a server you keep running the bot on). Clone the canonical template repository and install it.

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

Next: 5. Create and connect a Slack App

5. Create and connect a Slack App

Follow the full procedure in slack-bot/SLACK_APP_SETUP.md (already in the repository). In short:

api.slack.com/apps → Create New App → From scratch
OAuth & Permissions → add Bot Token Scopes: chat:write, app_mentions:read, channels:history, channels:read, groups:history, groups:read, im:history, im:read, im:write (optional: users:read)
Enable Socket Mode → issue an App-Level Token (connections:write scope) → copy xapp-...
Enable Event Subscriptions → subscribe to app_mention, message.im, message.channels, message.groups
Install to Workspace → copy the Bot User OAuth Token (xoxb-...)
Copy slack-bot/.env.example to .env and fill in SLACK_BOT_TOKEN (xoxb-), SLACK_APP_TOKEN (xapp-), and WORKSPACE_DIR
Run node index.js (or pm2 start index.js --name giipclaude-bot)

If something goes wrong, check the "Troubleshooting" table at the bottom of SLACK_APP_SETUP.md first.

Next: 6. Prepare a Slack channel

6. Prepare a Slack channel

Create the Slack channel the bot will respond in, or pick an existing one.
Invite the bot to that channel with /invite @<bot name>.
Look up the channel ID: right-click the channel name → View channel details → the C0XXXXXXXXX-style ID at the bottom.

Next: 7. Finish the GIIP linking

7. Finish the GIIP linking

Once you've confirmed the bot is alive in Slack, link that channel to the SK/csn you issued in step 3. Message the bot directly (or use the channel you're connecting) and enter the following commands in order.

giip account set <login_id> <SK> <csn>
giip channel set <project_name> <channel_id>
giip project set <project_name> <csn>

<login_id>: an email or similar that identifies this account (display purposes, e.g. you@example.com)
<SK>: the value issued in step 3
<csn>: the project number confirmed in step 1
<project_name>: a lowercase identifier you choose freely (used to route giip issue registrations)

Once all the commands succeed, you can say something like @<bot name> register issue <content> in that channel to register a giip issue right away.

⚠️ For a brand-new project: giip project set automatically tries to grant the bot's DB access permission (tUserPerCorp), but a completely new csn will fail this automatic grant due to a security gate (this is intended behavior). When that happens, the command response shows a warning and a follow-up giip issue is automatically registered under csn 47 — a GIIP administrator needs to see that issue and manually grant the permission by adding one line to giipdb/data/seed_tUserPerCorp_botuser.sql. Only this step needs admin intervention; everything else is fully self-service.

Next: Notifications you will receive

Notifications you will receive

Once the linking is done, every time a comment is added to an issue a notification is sent to that project's (csn) Slack channel. It makes no difference whether a person left the comment from the web UI or a bot left it.

Notification settings must be enabled for you to receive them: notifications are only sent when that project's notification settings are active. If no settings exist or they are turned off, no notification arrives — this is normal behavior, not an error. A GIIP administrator turns it on.
It usually takes 1-2 minutes to arrive: notifications are not sent instantly. When a comment is registered it first goes into a notification queue, and the delivery process picks items up and sends them every 2 minutes. Measured arrival times ranged from 11 to 100 seconds.
This is separate from new-issue notifications: the notification sent when a new issue is registered has its own delivery path (every 5 minutes), and it may arrive in a different channel than comment notifications. One arriving does not mean the other will.

⚠️ If no notification arrives: first check whether you waited more than 2 minutes — because of the 2-minute cycle described above, it is normal for it not to arrive the instant you post a comment. Next, check whether that project's notification settings are enabled. If neither applies and notifications still do not arrive, contact your GIIP administrator.

Version: 2.1 (added the "Notifications you will receive" section) Last Updated: 2026-10-22 Source File: giipv3/public/help/slack-bot-setup.en.md

← PreviousMQE Notification Settings Next →MQE Technical Spec

Learn more about the product →