GitLab plugin for Neovim - gitlab.vim

The GitLab plugin integrates GitLab with Neovim, and is built in Lua.

GitLab for Neovim supports GitLab Duo Code Suggestions. Code Suggestions provides a LSP (Language Server Protocol) server, to support the built-in Control+x, Control+o Omni Completion key mapping:

Mode Key mappings Type Description
INSERT Control+x, Control+o Built-in Requests completions from GitLab Duo Code Suggestions through the language server.
NORMAL <Plug>(GitLabToggleCodeSuggestions) <Plug> Toggles Code Suggestions on or off for the current buffer. Requires configuration.

Install the extension

Prerequisites:

  • For both GitLab.com and self-managed, you have GitLab version 16.1 or later. While many extension features might work with earlier versions, they are unsupported.
    • The GitLab Duo Code Suggestions feature requires GitLab version 16.8 or later.
  • You have Neovim version 0.9 or later.

To install the extension, follow the installation steps for your chosen plugin manager:

Run this command to include this project with packadd on startup:

git clone https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim.git ~/.local/share/nvim/site/pack/gitlab/start/gitlab.vim

Add this plugin to your lazy.nvim configuration:

{
  'git@gitlab.com:gitlab-org/editor-extensions/gitlab.vim.git',
  -- Activate when a file is created/opened
  event = { 'BufReadPre', 'BufNewFile' },
  -- Activate when a supported filetype is open
  ft = { 'go', 'javascript', 'python', 'ruby' },
  cond = function()
    -- Only activate if token is present in environment variable.
    -- Remove this line to use the interactive workflow.
    return vim.env.GITLAB_TOKEN ~= nil and vim.env.GITLAB_TOKEN ~= ''
  end,
  opts = {
    statusline = {
      -- Hook into the built-in statusline to indicate the status
      -- of the GitLab Duo Code Suggestions integration
      enabled = true,
    },
  },
}

Declare the plugin in your packer.nvim configuration:

use {
  "git@gitlab.com:gitlab-org/editor-extensions/gitlab.vim.git",
}

Configure the extension

  1. Configure environment variables. While these are the most common, a full list is available in this plugin’s help text at doc/gitlab.txt:

    Environment variable Default Description
    GITLAB_TOKEN. not applicable The default GitLab personal access token to use for authenticated requests. If provided, skips interactive authentication.
    GITLAB_VIM_URL. https://gitlab.com Override the GitLab instance to connect with. Defaults to https://gitlab.com.

  2. Configure your desired file types. For example, because this plugin supports Ruby, it adds a FileType ruby auto-command. To configure this behavior for additional file types, add more file types to the code_suggestions.auto_filetypes setup option:

    require('gitlab').setup({
  statusline = {
    enabled = false
  },
  code_suggestions = {
    # For the full list of default languages, see the 'auto_filetypes' array in
    # https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/blob/main/lua/gitlab/config/defaults.lua
    auto_filetypes = { 'ruby', 'javascript' }, -- Default is { 'ruby' }
  }
})

  3. Configure Omni Completion to set up the key mapping to trigger Code Suggestions.

  4. Optional. Configure <Plug> key mappings.

  5. Optional. Set up helptags using :helptags ALL for access to :help gitlab.txt.

Configure Omni Completion

To enable Omni Completion with Code Suggestions:

  1. Create a personal access token with the api scope.

  2. Install the Code Suggestions language server.

  3. Optional. Consider configuring Omni Completion’s dialog even for a single suggestion:

    vim.o.completeopt = 'menu,menuone'

When working in a supported file type, open the Omni Completion menu by pressing Ctrl+x then Ctrl+o.

Configure <Plug> key mappings

For convenience, this plugin provides <Plug> key mappings. To use the <Plug>(GitLab...) key mapping, you must include your own key mapping that references it:

-- Toggle Code Suggestions on/off with CTRL-g in normal mode:
vim.keymap.set('n', '<C-g>', '<Plug>(GitLabToggleCodeSuggestions)')

Disable gitlab.statusline

By default, this plugin enables gitlab.statusline, which uses the built-in statusline to show the status of the Code Suggestions integration. If you want to disable gitlab.statusline, add this to your configuration:

require('gitlab').setup({
  statusline = {
    enabled = false
  }
})

Report issues with the extension

Report any issues, bugs, or feature requests in the gitlab.vim issue queue.

Submit your feedback in issue 22 in the gitlab.vim repository.

Uninstall the extension

To uninstall the extension, remove this plugin and any language server binaries with these commands:

rm -r ~/.local/share/nvim/site/pack/gitlab/start/gitlab.vim
rm ~/.local/share/nvim/gitlab-code-suggestions-language-server-*