Review pull requests and manage issues across GitHub, GitLab, Bitbucket and Jira without leaving your editor.
[!CAUTION] Still in early development, will have breaking changes!
Quick links
{
"emrearmagan/atlas.nvim",
dependencies = {
"nvim-tree/nvim-web-devicons", -- optional but recommended
"esmuellert/codediff.nvim", -- optional (PullRequest diff)
"sindrets/diffview.nvim", -- optional; or "dlyongemallo/diffview-plus.nvim"
},
-- See Configuration below
---@type AtlasConfig
opts = {},
}
vim.pack.add({
"https://github.com/emrearmagan/atlas.nvim",
})
-- See Configuration below
require("atlas").setup({})
0.10+git and curl on $PATH*.atlassian.net) or Jira Server REST API v2api.bitbucket.org)gh) authenticated with gh auth logingitlab.com or self-hosted), Personal Access Token with api scope[!tip] It's a good idea to run
:checkhealth atlasto see if everything is set up correctly.
Run :Atlas review in a Git repository to pick a pull request, or pass a PR URL directly. Atlas opens it in your configured diff viewer.
[!NOTE] Alternative viewers: CodeDiff requires v3.0.0 or newer. Diffview and Diffview-plus are also supported. These viewers can display Atlas comment, task, and note overlays, but their integrations rely on plugin internals and may break after upstream changes.
Notes let you leave something on a diff without posting it to the pull request. Each note is attached to a file and line and can be an ISSUE, SUGGESTION, NOTE, or PRAISE.
For scripts, use bin/atlas-notes. Notes added there appear in AtlasDiff, CodeDiff, Diffview, Diffview-plus, and :Atlas notes:
./bin/atlas-notes add \
--target https://github.com/owner/repository/pull/123 \
--file lua/review_queue.lua --line 19 \
--context "local item = queue[index]" \
--type suggestion --body "Should this be a bool?"
My dotfiles include a Pi extension that wraps this script so review agents can list and add notes.
Use your configured language servers for hover and go-to-definition on the new side of AtlasDiff or CodeDiff.
Atlas uses a temporary worktree and removes it when the diff closes. Set link to symlink dependency folders from your local checkout. See Pulls Configuration for all options.
Browse a repository's README, pull requests, issues, builds, branches, tags and releases. Use :Atlas browse . for the current repository, or pass a repository URL.
View pipelines and their jobs, inspect their status, and read job logs directly in Atlas.
Use :Atlas pipelines <target> with a branch name, PR URL or number (123, #123, or GitLab !123), or a build URL. Branch names use the local repository; :Atlas pipelines . opens builds for the current branch.
Atlas uses your provider's CI by default. Set ci.backend to use your own. For Bamboo on Bitbucket, use require("atlas.pulls.pipelines.bamboo").new(opts) with host, user, and password.
providers = {
github = {
ci = {
backend = {
fetch = function(context, opts, done)
-- Fetch pipelines with their stages and jobs.
done({}, nil)
end,
fetch_job = function(context, pipeline, job, done)
-- Fetch the updated job, including any steps.
done(job, nil)
end,
fetch_job_log = function(context, pipeline, job, done)
-- Fetch the job's raw log output.
done({ raw = "Your log output here" }, nil)
end,
parse = function(log)
-- Return cleaned lines or your own nested groups.
return log.lines
end,
actions = {
-- Add your actions here.
},
},
highlights = {
{ pattern = "^FAIL%s", level = "error" },
{ pattern = "deprecated", level = "warn", hl_group = "DiagnosticWarn" },
},
},
},
}
ci.highlights controls log highlighting using Lua patterns. Set level for a severity color or hl_group for an existing Neovim highlight group.
Add project-specific actions to pull requests and issues. Custom actions receive the current item and provider context, making it possible to call local scripts, open repositories in tmux, copy branch names, or connect Atlas to your own tooling.
pulls = {
repo_config = {
paths = {
["your-workspace/*"] = "~/code/repos/*",
},
settings = {},
},
custom_actions = {
{
id = "show_repo_status",
label = "Show repository status",
icon = "",
confirmation = true,
---@param pr PullRequest
---@param ctx AtlasPullsCustomActionContext
---@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
local function write(_, data)
if data then ctx.write(data) end
end
vim.system({ "git", "status", "--short" }, {
cwd = ctx.repo_path,
stdout = write,
stderr = write,
}, function(result)
if result.code ~= 0 then
done(false, "Failed to read repository status")
return
end
done(true, "Repository status loaded")
end)
end,
},
},
},
issues = {
custom_actions = {
{
id = "copy_branch_name",
label = "Copy branch name",
icon = "",
confirmation = false,
---@param issue Issue
---@param ctx AtlasIssuesCustomActionContext
---@param done fun(ok: boolean|nil, message: string|nil)
run = function(issue, ctx, done)
local branch = string.format("%s/%s", issue.key, issue.title:lower():gsub("%s+", "-"))
vim.fn.setreg("+", branch)
done(true, "Copied: " .. branch)
end,
},
},
},
Use ctx.write(text) to show output and done(ok, message) to finish the action.
ctx.write("Running checks...\n")
done(true, "Checks passed")
Use :Atlas create [pr|issue] to create a pull request from the current branch or a new issue. For pull requests, Atlas can fill the description from your template or commits.
Save searches as bookmarks, or press * to star a pull request or issue. Both appear alongside your configured views.
:Atlas diff main...HEAD.{
ui = {
-- Set either to false to keep your existing statusline.
statusline = {
atlas = true, -- Dashboards, details, and other non-diff Atlas views.
diff = true, -- Diff and review views.
},
-- "auto", "default", "snacks", or "fzf-lua".
picker = "auto",
-- Make the main Atlas dashboard a listed buffer.
listed_buffer = false,
},
providers = {
---@type AtlasGitHubConfig
github = {
-- hostname = "github.company.com", -- Defaults to GH_HOST, then github.com.
cache_ttl = 300, -- Set to 0 to disable caching.
},
---@type AtlasGitLabConfig
gitlab = {
base_url = "https://gitlab.com",
-- Personal Access Token with `api` scope:
-- https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html
token = vim.env.GITLAB_TOKEN,
cache_ttl = 300, -- Set to 0 to disable caching.
},
---@type AtlasBitbucketConfig
bitbucket = {
user = vim.env.BITBUCKET_USER,
token = vim.env.BITBUCKET_TOKEN,
cache_ttl = 300, -- Set to 0 to disable caching.
},
---@type AtlasJiraConfig
jira = {
base_url = "https://your-site.atlassian.net",
email = "you@example.com", -- Required for basic authentication only.
--- See: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
token = "your_jira_api_token",
auth_method = "basic", -- "basic" or "bearer", defaults to "basic". If using bearer, set `token` to your API token.
api_type = "cloud", -- either "cloud" or "server", defaults to "cloud". Cloud API is v3, server API is v2
cache_ttl = 300, -- Set to 0 to disable caching.
},
},
-- See Pulls Configuration below.
pulls = { },
-- See Issue Configuration below.
issues = { },
}
:Atlas - Pick a command:Atlas pulls [provider] - Open a pull-request provider dashboard:Atlas issues [provider] - Open an issue provider dashboard:Atlas review [pull-request-url] - Review a pull request with the configured diff viewer:Atlas diff <target> - Open a Git range or pull request with the configured diff viewer; a target is required:Atlas pipelines [target|.] - Open pipelines by branch name, PR URL or number, or build URL; . uses the current branch:Atlas create [pr|issue] - Create a pull request or issue:Atlas search [provider] - Search configured pull-request and issue providers:Atlas open [target|.] - Open a provider URL, Jira key, a PR/issue number in the current repository, or the current repository:Atlas browse [repository URL|.] [page] - Open the repository browser, e.g. :Atlas browse . branches:Atlas notes [target] - Inspect notes:Atlas clear [cache|notes|stars] - Clear all Atlas data or only cached data and cloned repositories, notes, or starred items:Atlas logs - Toggle Atlas logs:Atlas console - Open the latest command outputUse :Atlas pulls [provider] to browse and manage pull requests from GitHub, Bitbucket, and GitLab.
Shared authentication and endpoints are configured in the top-level providers table.
pulls = {
delete_notes = false, -- Delete notes after approval or merge.
default_merge_method = "merge", -- "merge" or "squash".
default_delete_source_branch = false,
git_transport = "https", -- "https" or "ssh" for Atlas-managed Git remotes.
description = {
include_summary = true,
include_commit_hashes = true,
include_related = true,
include_diffstat = false,
},
-- Replaces the built-in Conventional Comments templates.
comment_templates = {
insert_mode = true, -- Enter Insert mode after applying a template.
items = {
{ label = "Suggestion", text = "suggestion: " },
{ label = "Issue", text = "issue: " },
{ label = "Nitpick", text = "nitpick: " },
},
},
diff = {
-- "auto", or a command that accepts explicit <base>...<head> Git revisions.
open_cmd = "auto", -- CodeDiff, DiffviewOpen or AtlasDiff
comment_display = "virtual_lines", -- "virtual_lines" or compact "virtual_text" hints.
review_panel = {
hidden = true, -- Set false to show the review panel when a diff opens.
height = 10,
},
-- AtlasDiff options; external viewers use their own configuration.
layout = "inline", -- "inline" or "side-by-side".
compact = true, -- Start with only changed hunks and surrounding context visible.
lsp = {
-- Back the new side of the diff with a detached worktree at the PR head so it is made of
-- real files and your language servers attach to it (AtlasDiff and CodeDiff). Off by default.
enabled = false,
-- Defaults to `stdpath("cache")/atlas/worktrees/<repo>/pr-<id>` (or `<repo>/<sha>` without a PR).
-- May be an absolute path, or a function receiving
-- { repo_root, repo_full_name, pr_id, head_sha, default } that returns a path or nil.
dir = nil,
-- Directories symlinked from your checkout into the worktree so servers can resolve
-- dependencies. These are the same directories on disk, not copies.
link = {}, -- e.g. { "node_modules", ".venv" }
},
explorer = {
grouped = true, -- Group changed files by directory.
hidden = false,
show_commits = false, -- Set true to show commits below changed files initially.
width = 40,
initial_focus = "explorer", -- "explorer" or "diff".
preview = false, -- Show a file as soon as the explorer cursor moves onto it.
focus_on_select = false, -- Move into the diff after selecting a file.
ignore = { ".git/**", ".jj/**" },
},
},
repo_config = {
-- Maps `namespace/repo` to local paths. Used for checkout, diffs, and custom actions.
paths = {
["your-workspace/*"] = "~/code/repos/*",
["your-workspace/atlas"] = "~/code/atlas",
["group/subgroup/*"] = "~/code/subgroup/*",
},
settings = {
["your-workspace/atlas"] = {
readme = "README.md", -- optional, defaults to README.md
pr_template = ".github/pull_request_template.md", -- optional, defaults to .github/pull_request_template.md
merge_method = "squash", -- Overrides default_merge_method.
delete_source_branch = true, -- Overrides default_delete_source_branch when merging.
},
},
},
custom_actions = {}, -- See :help atlas-custom-actions.
},
pulls = {
---@type AtlasGitHubPullsConfig
github = {
---@type AtlasGitHubViewConfig[]
views = {
{
name = "My PRs",
key = "1",
layout = "plain", -- "compact", "grouped", or "plain"
-- current_repo = true, -- Limit this view to the local repository.
search = "author:@me sort:updated-desc",
},
{
name = "Team",
key = "2",
layout = "compact",
search = "org:your-org sort:updated-desc",
},
{
name = "Repo",
key = "3",
layout = "grouped",
search = "repo:your-org/your-repo",
},
},
bookmarks = {
key = "S", -- default
label = "Search", -- default
items = {
["Drafts"] = "is:pr is:draft author:@me",
["Recently merged"] = "is:pr is:merged author:@me sort:updated-desc",
["Review requested"] = "is:pr is:open review-requested:@me",
},
},
},
},
pulls = {
---@type AtlasBitbucketPullsConfig
bitbucket = {
---@type AtlasBitbucketViewConfig[]
views = {
{
name = "Me",
key = "M",
layout = "compact", -- "compact", "grouped", or "plain"
-- current_repo = true, -- Remove repo:/project: targets from search when enabled.
-- https://developer.atlassian.com/cloud/bitbucket/rest/#filter-and-sort-api-objects
search = 'repo:your-workspace/standalone-repo project:your-workspace/CORE author.nickname = "your-name"',
},
{
name = "Team",
key = "1",
layout = "grouped",
search = 'project:your-workspace/TEAM destination.branch.name = "main"',
},
},
bookmarks = {
key = "S", -- default
label = "Search", -- default
items = {
["Atlas"] = {
layout = "grouped",
search = 'repo:your-workspace/atlas project:your-workspace/ATLAS title ~ "atlas"',
},
},
},
},
},
pulls = {
---@type AtlasGitLabPullsConfig
gitlab = {
---@type AtlasGitLabPullsViewConfig[]
views = {
{
name = "Assigned",
key = "1",
layout = "grouped", -- "compact", "grouped", or "plain"
scope = "assigned_to_me",
-- current_repo = true, -- Limit this view to the local repository.
},
{
name = "Waiting for review",
key = "3",
scope = "reviews_for_me",
state = "opened", -- "opened", "closed", "merged", or "all".
review_states = { "UNREVIEWED", "REVIEW_STARTED" },
},
-- Single project
{
name = "GitLab",
key = "G",
project = "gitlab-org/gitlab",
target_branch = "main",
},
-- Projects directly in this group
{
name = "GitLab Org",
key = "O",
group = "gitlab-org",
},
},
bookmarks = {
key = "S", -- default
label = "Search", -- default
items = {
["Reviewing"] = { scope = "reviews_for_me" },
["Created by me"] = { scope = "created_by_me" },
},
},
},
},
Use :Atlas issues [provider] to browse and manage Jira, GitHub, and GitLab issues.
Shared authentication and endpoints are configured in the top-level providers table.
issues = {
with_relationships = true, -- Fetch parent/subissue relationships for plain issue tree views.
custom_actions = {}, -- See :help atlas-custom-actions.
}
Issue views support plain and compact layouts. Jira also supports board, which
groups the current page by workflow status.
[!IMPORTANT] The markdown editor for issue descriptions and comments is still experimental and may not work perfectly in all cases. You can toggle between markdown and ADF view in the overview tab to see the raw ADF content and how it translates to markdown. If you encounter any issues with the markdown editor, please open an issue with details.
issues = {
---@type AtlasJiraIssuesConfig
jira = {
---@type AtlasJiraViewConfig[]
views = {
{
name = "My Board",
key = "M",
layout = "board",
jql = "project = KAN AND assignee = currentUser() ORDER BY updated DESC",
},
{
name = "Team Board",
key = "T",
layout = "compact",
jql = "project = KAN ORDER BY updated DESC",
},
},
bookmarks = {
key = "J", -- default
label = "JQL", -- default
items = {
["Backlog"] = "project = KAN AND statusCategory != Done AND (sprint IS EMPTY OR sprint NOT IN openSprints()) ORDER BY Rank ASC",
["Next sprint"] = "project = KAN AND sprint in futureSprints() ORDER BY Rank ASC",
["My open"] = "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC",
},
},
project_config = {
-- The Jira custom field ID used for story points. Defaults to "customfield_10016".
story_points_field = "customfield_10016",
-- Override issue type styles by name (case-insensitive).
issue_types = {
bug = { icon = "" },
maintenance = { icon = "", hl_group = "AtlasTextWarning" },
infrastructure = { icon = "", hl_group = "AtlasLogInfo" },
},
-- Icons for issue statuses and the transition picker; names override categories.
status_icons = {
new = "●",
indeterminate = "",
done = "",
["In Review"] = "",
["Blocked"] = "",
},
-- Custom fields to display per project; replace KAN with your project key.
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" or "table"
},
},
},
},
},
issues = {
---@type AtlasGitHubIssuesConfig
github = {
---@type AtlasGitHubIssuesViewConfig[]
views = {
{
name = "Assigned",
key = "1",
layout = "plain",
-- current_repo = true, -- Limit this view to the local repository.
search = "assignee:@me is:open",
},
{
name = "Created",
key = "2",
layout = "compact",
search = "author:@me is:open",
},
{
name = "Mentions",
key = "3",
layout = "plain",
search = "mentions:@me is:open",
},
},
bookmarks = {
key = "S", -- default
label = "Search", -- default
items = {
["Bugs"] = "is:issue is:open label:bug",
["Recently closed"] = "is:issue is:closed author:@me sort:updated-desc",
},
},
},
},
issues = {
---@type AtlasGitLabIssuesConfig
gitlab = {
---@type AtlasGitLabIssuesViewConfig[]
views = {
{
name = "Assigned",
key = "1",
scope = "assigned_to_me",
state = "opened",
-- current_repo = true, -- Limit this view to the local repository.
},
{
name = "Created",
key = "2",
scope = "created_by_me",
state = "opened",
},
{
name = "All open",
key = "3",
scope = "all",
state = "opened",
},
},
bookmarks = {
key = "S", -- default
label = "Search", -- default
items = {
["Closed"] = { scope = "created_by_me", state = "closed" },
},
},
},
},
Atlas emits these User events after the corresponding cleanup or setup has completed:
AtlasUIClosed for the main pulls/issues dashboard.AtlasDiffOpened and AtlasDiffClosed for diff sessions in AtlasDiff, CodeDiff, and Diffview.AtlasDiffFileChanged when the current diff file changes in any of these viewers.Set an action to false to disable it, or set it to a list to add aliases.
keymaps = {
ui = {
help = "g?", -- { "g?", "<leader>?" } would add aliases
close = "q", -- false would disable it
next_item = "j",
previous_item = "k",
previous_column = "h",
next_column = "l",
first_item = "gg",
last_item = "G",
select = "<CR>",
submit = "<C-s>",
delete = "dd",
comments = {
add = { "a", "i" },
reply = "c",
edit = "e",
react = "gr",
},
toggle_panel = "p",
cycle_layout = "t",
toggle_fold = "za",
toggle_all_folds = "zA",
toggle_description_mode = "<leader>m",
previous_panel_tab = "<S-Tab>",
next_panel_tab = "<Tab>",
notifications = {
open = "N",
mark_read = "r",
mark_done = "d",
},
toggle_subscription = "gS",
toggle_star = "*",
refresh = "r",
refresh_view = "R",
next_page = "]p",
previous_page = "[p",
open_actions = "A",
open_in_browser = "gx",
open_references = "gl",
copy_id = "y",
copy_url = "Y",
show_details = "K",
search = "?",
edit_search = "i",
},
picker = {
next_item = { "<Down>", "<C-n>", "<C-j>" },
previous_item = { "<Up>", "<C-p>", "<C-k>" },
select = { "<CR>", "<C-s>" },
toggle = "<Tab>",
close = { "q", "<Esc>" },
},
issues = {
transition_issue = "gs",
change_assignee = "ga",
change_reporter = "gr",
edit_issue = "ge",
create_issue = "c",
},
pulls = {
open_diff = "gd",
checkout = "gc",
open_repository = "o",
edit_pr = "ge",
review = {
show_details = "K", -- File/commit details.
toggle_file_reviewed = "-",
approve = "<leader>ga",
request_changes = "<leader>gr",
submit_review = "<leader>gs",
add_task = "<leader>t",
comment_templates = "gT",
toggle_resolved = "x",
next_comment = "]c",
prev_comment = "[c",
next_note = "]n",
prev_note = "[n",
add_comment = "c",
submit_comment = "C",
add_suggestion = "s",
submit_suggestion = "S",
add_note = "<leader>n",
view = {
external_help = "gA", -- External diff viewer help.
toggle_review_panel = "gR",
toggle_detail_panel = "gD",
toggle_comments = "gH",
},
explorer = {
toggle_commits = "gC",
next_unreviewed_file = "]u",
prev_unreviewed_file = "[u",
find_file = "<leader>f",
},
-- Built-in navigation; external viewers use their own keys.
atlas = {
next_file = { "]f", "<Tab>" },
prev_file = { "[f", "<S-Tab>" },
toggle_explorer = "<leader>b",
focus_explorer = "<leader>e",
open_file = "gf",
toggle_view_mode = "i",
next_hunk = "]h",
prev_hunk = "[h",
toggle_layout = "t",
toggle_compact = "gc",
},
},
pipelines = {
next_job = { "]j", "<Tab>" },
previous_job = { "[j", "<S-Tab>" },
show_history = "gH",
toggle_raw_logs = "gL",
toggle_auto_refresh = "gR",
},
filters = {
open = "gpo",
merged = "gpm",
declined = "gpd",
},
},
},
You can add custom keymaps to run Atlas actions, commands, or your own Lua functions.
local actions = require("atlas.pulls.actions")
keymaps = {
pulls = {
custom = {
{
key = "gP",
desc = "Open pipelines",
callback = function(context, done)
actions.run("open_pipelines", context, done)
end,
},
},
},
issues = {
custom = {
{
key = "<leader>as",
desc = "Atlas search",
callback = function()
vim.cmd("Atlas search")
end,
},
},
},
}
Thank you to everyone who has contributed to Atlas! ❤️
Contributions are welcome! If you'd like to contribute, please open an issue or pull request on GitHub. See CONTRIBUTING.md.
MIT License - see LICENSE for details.