Discord Forum to Jira Bridge Deployment Manual

1) Overview

The service listens for newly created Discord forum threads in one target forum channel and creates one Jira issue per thread. A local mapping file stores Discord thread ID to Jira issue key so the same thread is never submitted twice.

How the flow works

Bot receives a thread creation event from Discord.
Service checks that the thread belongs to the configured forum channel.
Service fetches the starter message content.
Service builds an Atlassian Document Format description and creates a Jira issue.
Service writes thread ID and issue key mapping to disk.

This tool currently syncs new forum threads only. It does not sync follow-up replies, Jira comments, or status changes.

2) Prerequisites

Node.js 18.17 or newer.
A Discord server with a forum channel.
A Discord bot token and bot invited to the server.
A Jira Cloud site, user email, API token, and project key.
Network access from the host to Discord and Jira APIs.

Keep all secrets out of source control. Never commit your bot token or Jira API token.

3) Account Preparation

Discord setup

Create the bot in the Discord Developer Portal.
Invite it to your server with permissions to view channels and read message history.
Enable Developer Mode in Discord client settings.
Right-click your target forum channel and copy its channel ID.

Jira setup

Create a Jira API token in Atlassian account security settings.
Confirm the Jira user can create issues in the target project.
Identify project key and preferred issue type name (default is Bug).

4) Environment Variables

Copy your example environment file and set all values. This service exits on startup if any required values are missing.

copy .env.example .env

Variable	Required	Description
`DISCORD_BOT_TOKEN`	Yes	Token for your Discord application bot user.
`DISCORD_FORUM_CHANNEL_ID`	Yes	The forum channel to monitor.
`JIRA_BASE_URL`	Yes	Your Jira site URL, for example `https://company.atlassian.net`.
`JIRA_EMAIL`	Yes	Atlassian account email used with API token.
`JIRA_API_TOKEN`	Yes	API token generated from Atlassian account settings.
`JIRA_PROJECT_KEY`	Yes	Target Jira project key such as `ENG` or `SUP`.
`JIRA_ISSUE_TYPE`	No	Issue type name, default is `Bug`.
`JIRA_SUMMARY_PREFIX`	No	Prefix added to issue summary, default `[Discord]`.
`PORT`	No	HTTP port for health endpoint, default `3000`.

5) Local Deployment

Step-by-step commands

npm install
npm run start

On startup, expect logs showing the health endpoint and the connected Discord bot identity. If the bot logs in successfully, the service is now watching your configured forum channel.

Health check

curl http://localhost:3000/health

The endpoint should return a JSON payload similar to {"status":"ok"}. If you changed PORT, call the same endpoint on the configured port.

First live test

Create a new thread in the configured Discord forum.
Observe service logs for a successful Jira issue creation message.
Open Jira and verify summary, description, and labels were generated correctly.
Inspect mapping file to confirm thread ID and Jira key are persisted.

6) Production Deployment

Recommended process supervisor (PM2)

npm install -g pm2
pm2 start src/index.js --name discord-jira-bridge
pm2 save
pm2 startup

PM2 keeps the process alive, restarts on failure, and lets you inspect logs quickly. For small and medium deployments, this is usually the fastest path to operational stability.

Persistence warning

The thread-to-issue mapping file is written to local disk. In ephemeral or containerized environments, mount a persistent volume for the data directory so mappings survive restarts.

If mapping data is lost, old threads can be re-processed and duplicate Jira issues may be created.

Hardening checklist

Use a dedicated service account for Jira with minimum required permissions.
Store secrets in host secret manager or environment injection system.
Restrict outbound network if your environment requires egress policy controls.
Set up log collection and alerting for failed Jira API calls.

7) Validation and Acceptance

Deployment acceptance criteria

Service starts without missing environment variable errors.
Health endpoint returns HTTP 200 with status ok.
New Discord forum thread creates one Jira issue in the target project.
Repeated processing does not duplicate issue for the same thread ID.
Failure conditions are visible in logs with actionable error details.

8) Troubleshooting Guide

Service exits immediately on startup

Cause: one or more required environment variables are not set. Resolution: verify all required variables and restart.

Discord bot connected, but no Jira issues are created

Cause: the event came from a different forum channel, or bot lacks permissions. Resolution: verify DISCORD_FORUM_CHANNEL_ID, bot server permissions, and test in the correct forum.

Jira API errors in logs

Cause: invalid token, invalid project key, unsupported issue type, or permission gap. Resolution: verify Jira credentials, project key, issue type name, and create-issue permission.

Duplicate issues

Cause: mapping file reset or unavailable persistent storage. Resolution: configure persistent volume for mapping data and back up mapping periodically.