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.

Table of Contents

1. Confirm your project (csn)
2. Create a service group
3. Issue an SK (Secret Key)
4. Install giip-fde-agent locally
5. Create and connect a Slack App
6. Prepare a Slack channel
7. 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.

1. Go to the Project Group List page.
2. 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:

1. api.slack.com/apps → Create New App → From scratch
2. 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)
3. Enable Socket Mode → issue an App-Level Token (connections:write scope) → copy xapp-...
4. Enable Event Subscriptions → subscribe to app_mention, message.im, message.channels, message.groups
5. Install to Workspace → copy the Bot User OAuth Token (xoxb-...)
6. Copy slack-bot/.env.example to .env and fill in SLACK_BOT_TOKEN (xoxb-), SLACK_APP_TOKEN (xapp-), and WORKSPACE_DIR
7. 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

1. Create the Slack channel the bot will respond in, or pick an existing one.
2. Invite the bot to that channel with /invite @<bot name>.
3. 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.

---

Version: 2.0 (fully revised as onboarding for the giip-fde-agent-based conversational bot) Last Updated: 2026-09-10 Source File: giipv3/public/help/slack-bot-setup.en.md