23 releases (11 breaking)

new 0.19.0 Jun 14, 2024
0.17.5 May 19, 2024

#23 in Text editors

Download history 87/week @ 2024-03-28 684/week @ 2024-04-04 189/week @ 2024-04-11 258/week @ 2024-04-18 735/week @ 2024-04-25 585/week @ 2024-05-02 572/week @ 2024-05-09 373/week @ 2024-05-16 300/week @ 2024-05-23 188/week @ 2024-05-30 98/week @ 2024-06-06

977 downloads per month

MIT license


GitLab CI Language Server (gitlab-ci-ls)


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.


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

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.


Initialization options:

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


  1. GitHub Releases: Download from the GitHub releases page.
  2. Homebrew (macOS): brew install alesbrelih/gitlab-ci-ls/gitlab-ci-ls
  3. Cargo (Rust Package Manager): cargo install gitlab-ci-ls
  4. 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"

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"))

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

  (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")))))


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


~427K SLoC