[!CAUTION] Still in early development, will have breaking changes!

jira.nvim

A Neovim plugin for managing JIRA tasks with a beautiful UI.

[!NOTE] Disucssion: How do you want to create, edit the jira ticket in this plugin? https://github.com/letieu/jira.nvim/discussions/1

Features

• 📋 View active sprint tasks
• 👥 Query tasks by custom JQL
• 📝 Read task as markdown
• 🔄 Change task status
• ⏱️ Log time on tasks
• 👤 Assign tasks
• 🎨 Git integration
• 🎨 Comment
• 🎨 Create, edit task
• ⏱️ Work report

---

Install

lazy.nvim

{
  "letieu/jira.nvim",
  opts = {
    -- Your setup options...
    jira = {
      base = "https://your-domain.atlassian.net", -- Base URL of your Jira instance
      email = "your-email@example.com",           -- Your Jira email (Optional for PAT)
      token = "your-api-token",                   -- Your Jira API token or PAT
      type = "basic",                             -- Authentication type: "basic" (default) or "pat"
      limit = 200,                                -- Global limit of tasks per view (default: 200)
    },
  },
}

---

Configuration

require('jira').setup({
  -- Jira connection settings
  jira = {
    base = "https://your-domain.atlassian.net", -- Base URL of your Jira instance
    email = "your-email@example.com",           -- Your Jira email (Optional for PAT)
    token = "your-api-token",                   -- Your Jira API token or PAT
    type = "basic",                             -- Authentication type: "basic" (default) or "pat"
    limit = 200,                                -- Global limit of tasks per view (default: 200)
  },

  -- Saved JQL queries for the JQL tab
  -- Use %s as a placeholder for the project key
  queries = {
    ["Next sprint"] = "project = '%s' AND sprint in futureSprints() ORDER BY Rank ASC",
    ["Backlog"] = "project = '%s' AND (issuetype IN standardIssueTypes() OR issuetype = Sub-task) AND (sprint IS EMPTY OR sprint NOT IN openSprints()) AND statusCategory != Done ORDER BY Rank ASC",
    ["My Tasks"] = "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC",
  },

  -- Project-specific overrides
  -- Still think about this config, maybe not good enough
  projects = {
    ["DEV"] = {
      story_point_field = "customfield_10035",      -- Custom field ID for story points
      custom_fields = { -- Custom field to display in markdown view
        { key = "customfield_10016", label = "Acceptance Criteria" }
      },
    }
  }
})

Alternatively, you can set Jira credentials using environment variables, which takes precedence over config:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_TOKEN="your-api-token"
export JIRA_AUTH_TYPE="basic" # or "pat"

Supported environment variables:

• JIRA_BASE_URL - Base URL of your Jira instance
• JIRA_EMAIL - Your Jira email (Optional for PAT)
• JIRA_TOKEN - Your Jira API token or PAT
• JIRA_AUTH_TYPE - Authentication type: "basic" (default) or "pat"

---

Usage

Run the following command to open the Jira board:

" Open board
:Jira <PROJECT_KEY>

" Open one task view (info)
:Jira info ISSUE_KEY

" Create new issue
:Jira create [PROJECT_KEY]

" Edit existing issue
:Jira edit ISSUE_KEY

If you don't provide a project key, you will be prompted to enter one.

Keybindings

Help

• H — Show help

Navigation & View

• <Tab> — Toggle node (Expand / Collapse)
• S, J, H — Switch view (Sprint, JQL, Help)
• q — Close board
• r — Refresh current view

Issue Actions (In board)

• i — Create issue / sub-task (under cursor)
• K — Quick issue details (popup)
• gd — Read task as info
• ge — Edit task
• gx — Open task in browser
• gs — Update status
• ga — Change assignee
• gw — Add time
• gb — Checkout / create branch
• go — Show child issues (sub-tasks)

---

Tips

• How to get custom field list -> go to https://your-domain.atlassian.net/rest/api/3/field

---

Development

Running Tests

make test

---

TODO

• Jira sprint board
• Config
• Expand, Collapse
• Read task (Markdown)
• Format time
• Backlog (via JQL Dashboard)
• Custom JQL & Saved Queries
• Change status
• Change assignee
• Log time
• Comment
• Create, Edit task
• Bulk actions
• Update UI when terminal size change ...

---

Thanks

Big thanks for gemini CLI free tier.

---

License

MIT © Tieu Le

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!