emrearmagan/atlas.nvim

github

workflow

13

0

0

0

CREATED

2026-02-08

UPDATED

2026-04-04

---

Atlas.nvim

A Neovim plugin for managing Bitbucket PRs and Jira issues without leaving your editor.

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

Using lazy.nvim

{
  "emrearmagan/atlas.nvim",
  dependencies = {
    "MeanderingProgrammer/render-markdown.nvim", -- optional but recommended
  },
  config = function()
    require("atlas").setup({
        bitbucket = { }, -- See configuration below
        jira = { },      -- See configuration below
    })
  end,
}

Using packer.nvim

use {
  "emrearmagan/atlas.nvim",
  config = function()
    require("atlas").setup({
        bitbucket = { }, -- See configuration below
        jira = { },      -- See configuration below
    })
  end
}

[!tip] It's a good idea to run :checkhealth atlas to see if everything is set up correctly.

Bitbucket

Configuration

return {
  "emrearmagan/atlas.nvim",
  config = function()
    require("atlas").setup({
      ---@type BitbucketConfig
      bitbucket = {
        user = os.getenv("BITBUCKET_USER") or "",
        token = os.getenv("BITBUCKET_TOKEN") or "",
        cache_ttl = 300,
        repo_config = {
          -- Maps `workspace/repo` to local paths. Used for checkout and custom actions.
          paths = {
            ["your-workspace/*"] = "~/code/repos/*",
            ["your-workspace/atlas"] = "~/code/atlas",
          },

          settings = {
            ["your-workspace/atlas"] = {
              readme = "README.md", -- optional, defaults to README.md
            },
          },
        },
        custom_actions = {}, -- See Custom Actions below.

        ---@type BitbucketViewConfig[]
        views = {
          {
            name = "Me",
            key = "M",
            layout = "compact", -- "compact" or "plain"
            repos = {
                { workspace = "your-workspace", repo = "atlas" },
            },

            ---@param pr BitbucketPR
            ---@param ctx table
            filter = function(pr, ctx)
              local user = ctx.user or {}
              return pr.author and pr.author.account_id == user.account_id
            end,
          },
          {
            name = "Others",
            key = "O",
            layout = "plain", -- "compact" or "plain"
            repos = {
              { workspace = "your-workspace", repo = "atlas" },
              { workspace = "your-workspace", repo = "other-repo" },
            },
          },
        },
      },
    })
  end,
}

Custom Actions

You can add custom PR actions under bitbucket.custom_actions.

Context type:

---@class BitbucketCustomActionContext
---@field repo_path string|nil
---@field pr BitbucketPR

Example:

bitbucket = {
  repo_config = {
    paths = {
      ["your-workspace/*"] = "~/code/repos/*",
    },
    settings = {},
  },
  custom_actions = {
    {
      id = "open_tmux_window",
      label = "Open repo in tmux window",
      confirmation = true, -- present a confirmation prompt before running the action
      ---@param pr BitbucketPR
      ---@param ctx BitbucketCustomActionContext
      ---@param done fun(ok: boolean|nil, message: string|nil)
      run = function(_, ctx, done)
        if not ctx.repo_path then
          done(false, "No repo path")
          return
        end

        vim.system({ "tmux", "new-window", "-c", ctx.repo_path }, { text = true }, function(res)
          vim.schedule(function()
            if res.code ~= 0 then
              done(false, "Failed to open tmux window")
              return
            end
            done(true, "Opened tmux window")
          end)
        end)
      end,
    },
  },
}

Features

• Multiple Bitbucket views
• PR tabs: overview, activity, comments, commits, files
• PR actions: merge, approve, request changes
• Add custom actions to PRs
• Resolve and checkout PR branches locally
• Pagination for API results (PRs, comments, commits, files, activity)
• Switch between open, merged and superseded PRs
• Bulk actions: approve/request changes on multiple PRs at once
• PR files: fuzzy filter changed files by path

Jira

[!NOTE] Inspired by jira.nvim since it fitted nicely in this here. I highly recommend checking out the original project for a more general-purpose solution.

Configuration

return {
  "emrearmagan/atlas.nvim",
  config = function()
    require("atlas").setup({
      ---@type JiraConfig
      jira = {
        base_url = os.getenv("JIRA_BASE_URL") or "",
        email = os.getenv("JIRA_EMAIL") or "",
        token = os.getenv("JIRA_TOKEN") or "",
        cache_ttl = 300,
        resolve_parent_issues = true,

        project_config = {
          KAN = {
            customfield_10003 = {
              name = "Approvers",
              format = function(value)
                if type(value) ~= "table" or #value == 0 then
                  return nil -- nil hides the field
                end

                return table.concat(value, ", ")
              end,
              hl_group = "AtlasChipActive",
              display = "chip", -- "chip" (default) or "table"
            },
          },
        },

        ---@type JiraViewConfig[]
        views = {
          {
            name = "My Board",
            key = "M",
            jql = "project = KAN AND assignee = currentUser() ORDER BY updated DESC",
          },
          {
            name = "Team Board",
            key = "T",
            jql = "project = KAN ORDER BY updated DESC",
          },
        },
      },
    })
  end,
}

Creating or Edit Issues (Experimental)

• Edit or create issue description directly from Overview.
• Supports markdown editing with markdown -> ADF conversion.

Comments

• Create, reply, edit, and delete comments directly in the Jira panel.

Features

• Create issues
• Issue panel tabs: overview, comments, history
• Jira actions: transition, change assignee, change reporter, edit title
• Full comment workflows (create, reply, edit, delete)
• Markdown -> ADF conversion for issue descriptions (experimental)
• View and edit issues as markdown
• Search issues
• Add support for custom fields in issue details
• Create and edit issue templates

Commands

• :AtlasJira - Open Jira issue picker
• :AtlasBitbucket - Open Bitbucket PR picker
• :AtlasLogs - Toggle Atlas logs

Keymaps

License

MIT License - see LICENSE for details.