GitLab CI Language Server (gitlab-ci-ls)

Disclaimer

This is an independent project and not an official GitLab product. It is intended to be used alongside yaml-language-server (yamlls), providing specialized support for GitLab CI files without replacing yamlls.

Features

Go To Definition: Navigate to definitions of jobs, includes, variables, needs, extends and variables.
Find References: Find all usages of jobs, extends and stages.
Autocompletion: Suggestions for extends, stages, needs, variables and components.
Hover Information: View documentation for job with merged definitions.
Diagnostics: Identifies issues with extends references, stage definitions, job needs usage and components.
Rename: Supports job renaming.

It also supports jump to included files. In case it is a remote file it tries to downloading using current workspace git setup and caches it locally.

Showcase

Note that this video doesn't include all functionalities.

Watch the video

Configuration

Initialization options:

cache: location for cached remote files
log_path: location for LS log

Installation

GitHub Releases: Download from the GitHub releases page.
Homebrew (macOS): brew install alesbrelih/gitlab-ci-ls/gitlab-ci-ls
Cargo (Rust Package Manager): cargo install gitlab-ci-ls
Mason (neovim): Github

Build from source

cargo build --release

Executable can then be found at target/release/gitlab-ci-ls

Integration with Neovim

Easiest way to use this using neovim is to install it using mason with combination of mason-lspconfig.

Important: To use it now you will have to set correct file type. Before it was attached on yaml file types, but I have decided that it brings too much confusion.

Example how to add it:

vim.api.nvim_create_autocmd({ "BufRead", "BufNewFile" }, {
  pattern = "*.gitlab-ci*.{yml,yaml}",
  callback = function()
    vim.bo.filetype = "yaml.gitlab"
  end,
})

Integration with VSCode

Extension can be found here.

This extension supports configuration which needs to be set up because gitlab-ci-ls itself isn't installed along with the extension but it needs to be downloaded from releases, brew or built from source.

vscode settings

Emacs lsp-mode configuration

To use gitlab-ci-ls with Emacs lsp-mode, reference the below sample configuration.

(add-to-list 'lsp-language-id-configuration '("\\.gitlab-ci\\.yml$" . "gitlabci"))
(add-to-list 'lsp-language-id-configuration '("/ci-templates/.*\\.yml$" . "gitlabci"))

(lsp-register-custom-settings
  '(("gitlabci.cache" "/path/where/remote/folders/will/be/cached")
    ("gitlabci.log_path" "/tmp/gitlab-ci-ls.log")))

(lsp-register-client
  (make-lsp-client :new-connection (lsp-stdio-connection '("gitlab-ci-ls"))
                  :activation-fn (lsp-activate-on "gitlabci")
                  :server-id 'gitlabci
                  :priority 10
                  :initialization-options (lambda () (gethash "gitlabci" (lsp-configuration-section "gitlabci")))))

TODO

[ ] Smarter way to initialize, it should support root_dir equal to nil and once file is opened it should receive/calculate new root.
[x] Fix VSCode completion. It seems it also needs a range to correctly update text.
[x] Rename to gitlab-ci-ls.
[x] References for stages
[ ] Variables can be set in matrixes as well, this is relevant for go to definition on variable.
[x] Support !reference
[x] Handle default keyword
[x] Handle components
[x] Push diagnostics, instead of pull based

alesbrelih / gitlab-ci-ls

readme