Provider setup

The plugin ships with a built-in Jira provider that connects to Jira Cloud via REST API v3. Configuration follows a three-level precedence: explicit config properties, plugin options, then environment variables.

Environment variables

The simplest setup uses environment variables. The plugin checks these automatically when no provider is configured explicitly.

Variable	Required	Default	Description
`JIRA_URL`	Yes	—	Jira Cloud base URL (e.g., `https://company.atlassian.net`)
`JIRA_EMAIL`	Yes	—	Atlassian account email
`JIRA_API_TOKEN`	Yes	—	Jira API token (create one here)
`JIRA_PROJECT_KEY`	For card creation	—	Project key (e.g., `PROJ`)
`JIRA_JQL`	No	Default JQL	Custom JQL filter
`JIRA_MAX_RESULTS`	No	`100`	Max results per API page (1-1000)
`JIRA_DEFAULT_ISSUE_TYPE`	No	`Task`	Default issue type for new cards
`JIRA_DISCORD_USER_ID_FIELD_ID`	No	—	Custom field ID containing Discord User IDs

.env

JIRA_URL="https://company.atlassian.net"
JIRA_EMAIL="team@example.com"
JIRA_API_TOKEN="ATATT3xFfGF0..."
JIRA_PROJECT_KEY="PROJ"
JIRA_JQL="labels = public"
JIRA_MAX_RESULTS="50"
JIRA_DEFAULT_ISSUE_TYPE="Story"

Config file setup

For more control, configure the provider in your plugin config file:

config/plugins/robojs/roadmap.ts

import { JiraProvider } from '@robojs/roadmap'

export default {
  provider: new JiraProvider({
    type: 'jira',
    options: {
      url: process.env.JIRA_URL,
      email: process.env.JIRA_EMAIL,
      apiToken: process.env.JIRA_API_TOKEN,
      projectKey: process.env.JIRA_PROJECT_KEY,
      jql: 'project = PROJ AND labels = public',
      maxResults: 50,
      defaultIssueType: 'Story'
    }
  })
}

config/plugins/robojs/roadmap.js

import { JiraProvider } from '@robojs/roadmap'

export default {
  provider: new JiraProvider({
    type: 'jira',
    options: {
      url: process.env.JIRA_URL,
      email: process.env.JIRA_EMAIL,
      apiToken: process.env.JIRA_API_TOKEN,
      projectKey: process.env.JIRA_PROJECT_KEY,
      jql: 'project = PROJ AND labels = public',
      maxResults: 50,
      defaultIssueType: 'Story'
    }
  })
}

You can also pass a plain config object instead of a provider instance:

config/plugins/robojs/roadmap.ts

export default {
  provider: {
    type: 'jira',
    options: {
      url: process.env.JIRA_URL,
      email: process.env.JIRA_EMAIL,
      apiToken: process.env.JIRA_API_TOKEN,
      projectKey: process.env.JIRA_PROJECT_KEY
    }
  }
}

config/plugins/robojs/roadmap.js

export default {
  provider: {
    type: 'jira',
    options: {
      url: process.env.JIRA_URL,
      email: process.env.JIRA_EMAIL,
      apiToken: process.env.JIRA_API_TOKEN,
      projectKey: process.env.JIRA_PROJECT_KEY
    }
  }
}

JQL filtering

JQL (Jira Query Language) controls which issues the plugin fetches. The default JQL fetches public Epics:

(issuetype = Epic AND (labels NOT IN ("Private") OR labels IS EMPTY)) OR labels IN ("Public")

Common JQL patterns:

// Public cards only
jql: 'project = PROJ AND labels = public'

// Exclude private cards
jql: 'project = PROJ AND labels != private'

// Active cards only (not resolved)
jql: 'project = PROJ AND resolution = Unresolved'

// Cards updated in last 30 days
jql: 'project = PROJ AND updated >= -30d'

// Multiple projects
jql: 'project IN (PROJ, OTHER) AND labels = roadmap'

// Public cards only
jql: 'project = PROJ AND labels = public'

// Exclude private cards
jql: 'project = PROJ AND labels != private'

// Active cards only (not resolved)
jql: 'project = PROJ AND resolution = Unresolved'

// Cards updated in last 30 days
jql: 'project = PROJ AND updated >= -30d'

// Multiple projects
jql: 'project IN (PROJ, OTHER) AND labels = roadmap'

See the Atlassian JQL documentation for the full query language reference.

Discord User ID custom field

Map Jira issues directly to Discord users by storing Discord User IDs in a Jira custom field. This bypasses the standard assignee mapping system.

Create a custom field in Jira

Create a text custom field in your Jira project (e.g., "Discord User ID").

Find the field ID

Note the custom field ID (e.g., customfield_10042). You can find this in the Jira field configuration or via the REST API.

Configure the plugin

.env

JIRA_DISCORD_USER_ID_FIELD_ID="customfield_10042"

Or in the config file:

    options: {
      discordUserIdFieldId: 'customfield_10042'
    }

    options: {
      discordUserIdFieldId: 'customfield_10042'
    }

Add Discord User IDs to issues

Enter a Discord User ID (17-19 digit number) in the custom field on Jira issues.

When this field is set, it takes priority over the standard Jira assignee mapping. Invalid IDs are logged and ignored, falling back to the assignee mapping.

Configuration precedence

The provider resolves configuration from multiple sources in this order:

Pre-instantiated provider in pluginOptions.provider (a RoadmapProvider instance)
Config object in pluginOptions.provider (a ProviderConfig with type and options)
Environment variables (JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN)
No provider — plugin loads but stays inactive

If the provider can't initialize (invalid credentials, network issues), the plugin loads but remains inactive. Commands check isProviderReady() and show guidance when the provider isn't configured.

Jira provider options

Prop

Type

Next steps

Configuration

Plugin options and column mapping.

Column mapping

Customize status-to-column mappings.

Assignee mapping

Map provider names to Discord users.

Provider setup

Configuration

Column mapping

Assignee mapping

On this page