repository·master·Indexed 25 days ago
https://github.com/pwntester/octo.nvimA Neovim plugin for editing and reviewing GitHub issues, pull requests, and discussions directly within the editor. It leverages the GitHub CLI to sync changes and provides a dedicated review mode for PRs, including diff navigation and commenting. Supports integration with pickers like telescope.nvim, fzf-lua, and snacks.nvim, and offers omnifunc completion for issues, PRs, and users.
Octo.nvim provides the following capabilities:
GitHub CLI via the octo.gh Lua module.Before using Octo.nvim, ensure your environment meets the following requirements:
>=0.10.0.gh auth refresh -s read:project to add the necessary scope.project scope instead.telescope.nvimfzf-luasnacks.nvimvim.ui.select)After installation, run :checkhealth octo to verify your setup.
To install Octo.nvim, use the following configuration with lazy.nvim. This setup includes telescope as the picker and defines several keybindings for common tasks like listing issues, pull requests, discussions, and notifications. It also includes the required plenary.nvim dependency.
{
"pwntester/octo.nvim",
cmd = "Octo",
opts = {
-- or "fzf-lua" or "snacks" or "default"
picker = "telescope",
-- bare Octo command opens picker of commands
enable_builtin = true,
},
keys = {
{
"<leader>oi",
"<CMD>Octo issue list<CR>",
desc = "List GitHub Issues",
},
{
"<leader>op",
"<CMD>Octo pr list<CR>",
desc = "List GitHub PullRequests",
},
{
"<leader>od",
"<CMD>Octo discussion list<CR>",
desc = "List GitHub Discussions",
},
{
"<leader>on",
"<CMD>Octo notification list<CR>",
desc = "List GitHub Notifications",
},
{
"<leader>os",
function()
require("octo.utils").create_base_search_command { include_current_repo = true }
end,
desc = "Search GitHub",
},
},
dependencies = {
"nvim-lua/plenary.nvim",
"nvim-telescope/telescope.nvim",
-- OR "ibhagwan/fzf-lua",
-- OR "folke/snacks.nvim",
"nvim-tree/nvim-web-devicons", -- optional if file_panel.icons is a function
},
}Octo.nvim provides a dedicated review mode for GitHub Pull Requests.
Octo review to enter review mode for the current branch.Octo <PR url>, Octo pr list, or Octo pr edit <PR number>) and run Octo review within that buffer.]q and [q to change panel entries.<localleader>ca (comment) or <localleader>sa (suggestion).Octo review commit to select a specific commit. The file panel will filter to show only files changed by that commit.Octo review comments to see pending comments. Press <CR> to jump to a selected comment.Octo review submit. A float window will appear for the top-level review comment.<C-m> to submit a comment.<C-a> to approve.<C-r> to request changes.Octo.nvim includes built-in omnifunc completion for issues, PRs, and users, triggerable via <C-x><C-o>.
To enable autocompletion when typing # (issues/PRs) or @ (users) in markdown files, add these mappings to your configuration:
-- Add these mappings for octo file type
vim.keymap.set("i", "@", "@<C-x><C-o>", { silent = true, buffer = true })
vim.keymap.set("i", "#", "#<C-x><C-o>", { silent = true, buffer = true })If you use nvim-cmp or blink.cmp, you can use the following sources for better integration:
cmp-git.blink-cmp-git.cmp-emoji or blink-emoji.nvim for markdown emoji completion.To enable Treesitter markdown parsing for Octo buffers, register the octo filetype to use the markdown language in your Treesitter configuration:
vim.treesitter.language.register('markdown', 'octo')Octo.nvim allows you to interact with GitHub issues, PRs, and discussions using the :Octo command or special octo:// URLs.
You can pass GitHub URLs directly to the command to open specific items:
" GitHub.com URLs
Octo https://github.com/pwntester/octo.nvim/issues/12
Octo https://github.com/pwntester/octo.nvim/pull/123
" GitHub Enterprise URLs (hostname is automatically detected)
Octo https://ghe.example.com/owner/repo/issues/456
Octo https://ghe.example.com/owner/repo/pull/789You can open issues and PRs directly using the octo:// protocol in any buffer (e.g., via :e). This is useful for working across multiple GitHub instances without changing global settings.
" Open from the default GitHub instance
:e octo://owner/repo/issue/123
:e octo://owner/repo/pull/456
" Open from a specific GitHub Enterprise instance
:e octo://ghe.example.com/owner/repo/issue/123
:e octo://ghe.example.com/owner/repo/pull/456Octo https://github.com/pwntester/octo.nvim/issues/12
Octo issue create
Octo issue create pwntester/octo.nvim
Octo comment add
Octo reaction add hooray
Octo issue edit pwntester/octo.nvim 1
Octo issue edit 1
Octo issue list createdBy=pwntester
Octo issue list neovim/neovim labels=bug,help\ wanted states=OPEN
Octo search assignee:pwntester is:pr
Octo search is:discussion repo:pwntester/octo.nvim category:"Show and Tell"Use the require('octo').setup() function to customize plugin behavior.
ssh_aliases: A table mapping SSH aliases to github.com. Use this if your .git/config uses an SSH alias for GitHub.suppress_missing_scope: A table to suppress warnings for missing GitHub scopes (e.g., projects_v2 = true).search.completion_overrides: Used to override completion for specific :Octo search qualifiers (e.g., to disable remote calls).mappings_disable_default: Set to true to disable all default key mappings.require('octo').setup({
ssh_aliases = {
["<THE ALIAS YOU HAVE LISTED IN ~/.ssh/config>"] = "github.com"
},
suppress_missing_scope = {
projects_v2 = true,
}
})Customize the icons displayed in the file panel using the file_panel.icons option. You can enable nvim-web-devicons by setting it to true, disable them with false, or provide a custom function that accepts (name, ext) and returns an icon, hl pair.
require("octo").setup({
file_panel = {
icons = function(name, _ext)
return require("mini.icons").get("file", name)
end,
},
})Use require"octo".setup { ... } to configure the plugin. The configuration covers pickers, remote defaults, UI elements, icon sets, and specialized mappings for discussions, issues, pull requests, and reviews.
Key configuration sections include:
picker: Select the picker engine (telescope, fzf-lua, snacks, or default).picker_config: Configure picker-specific settings like mappings and snacks custom actions.mappings: Define custom keybindings for different contexts (e.g., discussion, issue, pull_request, review_diff).ui: Control buffer appearance, including conceallevel and status column usage.pull_requests / issues / discussions: Set default sorting via order_by (fields: COMMENTS, CREATED_AT, UPDATED_AT; directions: DESC, ASC).gh_cmd: Specify the GitHub CLI command to use (defaults to gh).require"octo".setup {
picker = "telescope", -- or "fzf-lua" or "snacks" or "default"
picker_config = {
use_emojis = false,
search_static = true,
mappings = {
open_in_browser = { lhs = "<C-b>", desc = "open issue in browser" },
copy_url = { lhs = "<C-y>", desc = "copy url to system clipboard" },
copy_sha = { lhs = "<C-e>", desc = "copy commit SHA to system clipboard" },
checkout_pr = { lhs = "<C-o>", desc = "checkout pull request" },
merge_pr = { lhs = "<C-r>", desc = "merge pull request" },
},
snacks = {
actions = {
issues = {},
pull_requests = {},
notifications = {},
issue_templates = {},
search = {},
changed_files = {},
commits = {},
review_commits = {},
},
},
},
default_remote = { "upstream", "origin" },
default_merge_method = "merge",
default_delete_branch = false,
ssh_aliases = {["github.com-work"] = "github.com"},
gh_cmd = "gh",
-- ... other options
}Octo.nvim relies on the gh CLI tool for authentication.
If you see Cannot request projects v2, missing scope 'read:project', you must refresh your GitHub token with the required scope:
gh auth refresh -s read:projectAlternatively, suppress the warning in your Octo config using suppress_missing_scope = { projects_v2 = true }.
If you encounter authentication errors:
gh is logged in: If you are using a GITHUB_TOKEN, run GITHUB_TOKEN= gh auth login and follow the prompts. gh must be able to store credentials in a way accessible to subshells.require('octo').setup({
ssh_aliases = {
["<YOUR_ALIAS>"] = "github.com"
}
})GITHUB_TOKEN= gh auth loginOcto uses a unified command structure: Octo <object> <action> [arguments]. If no command is passed, Octo treats the argument as a URL to extract an issue or PR repository and number.
Common objects and actions include:
close, reopen, create [repo], develop, edit <number> [repo], list [repo] [key=value], search, reload, browser, url, subscription, pin, unpin.list [repo] [key=value], search, edit <number> [repo], reopen, create, close, checkout, commits, changes, diff, merge [merge|rebase|squash] [delete|nodelete], ready, draft, checks, reload, browser, url, subscription, sha, runs.list, fork, browser, url, subscription, view.add, suggest, delete, url, reply.add [label], remove [label], create [label], delete [label], edit [label].add [milestone], remove, create [milestone], list [repo].add [login], remove [login].list [repo], edit <number> [repo], browser, create [repo], reload, close, mark, unmark, reopen, search, subscription, category.