gh-actions.nvim

Plugin that improves support for Github Actions files in Neovim.

Features

• Syntax highlighting for Github Actions expressions thanks to tree-sitter-gh-actions-expressions. Compatible with ^0.3.0
• New predicate with its LSP configuration

Requirements

• Neovim >= 0.9.0
• nvim-treesitter
• gitignore parser (optional): for hashFiles() function
• json parser (optional): for fromJSON() function
• yaml parser: injection to its block_mapping_pair node

Install

Installation examples for lazy.nvim and packer.nvim:

[!IMPORTANT] This snippet is for neovim >= 0.11.0

{
  "nvim-treesitter/nvim-treesitter",
  lazy = false, -- if using `lazy.nvim`
  branch = 'main',
  -- `run` instead of `build` if using `packer.nvim`
  build = ':TSUpdate',
  -- `requires` instead of `dependencies` if using `packer.nvim`
  dependencies = { "Hdoc1509/gh-actions.nvim" },
  config = function()
    -- NOTE: register parser before installation
    require("gh-actions.tree-sitter").setup()

    require("nvim-treesitter").install({
      "gh_actions_expressions", -- required
      "gitignore", -- optional
      "json", -- optional
      "yaml", -- required
    })
  end,
}

Parser installation for previous versions of nvim-treesitter

ensure_install of main branch

[!IMPORTANT] This snippet is for neovim >= 0.11.0. See Minit README for some details about possible compatibility for neovim 0.10.

Use install module instead:

{
  "nvim-treesitter/nvim-treesitter",
  lazy = false, -- if using `lazy.nvim`
  branch = "main",
  -- `run` instead of `build` if using `packer.nvim`
  build = ":TSUpdate",
  -- prior or equal to:
  commit = "73adbe597e8350cdf2773e524eb2199841ea2ab6",
  -- posterior or equal to:
  -- commit = "0bb981c87604200df6c8fb81e5a411101bdf93af",
  -- `requires` instead of `dependencies` if using `packer.nvim`
  dependencies = { "Hdoc1509/gh-actions.nvim" },
  config = function()
    -- NOTE: register parser before installation
    require("gh-actions.tree-sitter").setup()

    require("nvim-treesitter.install").install({
      "gh_actions_expressions", -- required
      "gitignore", -- optional
      "json", -- optional
      "yaml", -- required
    })
  end,
}

configs module of old master branch

[!IMPORTANT] This snippet is for neovim >= 0.9.0.

{
  "nvim-treesitter/nvim-treesitter",
  lazy = false, -- if using `lazy.nvim`
  branch = "master",
  -- `run` instead of `build` if using `packer.nvim`
  build = ":TSUpdate",
  -- `requires` instead of `dependencies` if using `packer.nvim`
  dependencies = { "Hdoc1509/gh-actions.nvim" },
  config = function()
    -- NOTE: register parser before installation
    require("gh-actions.tree-sitter").setup()

    require("nvim-treesitter.configs").setup({
      ensure_installed = {
        "gh_actions_expressions", -- required
        "gitignore", -- optional
        "json", -- optional
        "yaml", -- required
      },
    })
  end,
}

Default configuration

gh-actions.tree-sitter setup

---@type GHActions.TS.Opts
{
  -- Whether to `generate` files from the grammar before building it
  from_grammar = nil,
  -- Path to local `tree-sitter-gh-actions-expressions`.
  path = nil,
  -- Remote url to `tree-sitter-gh-actions-expressions`
  url = "https://github.com/Hdoc1509/tree-sitter-gh-actions-expressions",
  -- Version or commit of `tree-sitter-gh-actions-expressions`
  revision = nil,
  -- Branch of `tree-sitter-gh-actions-expressions`
  branch = "release",
}

is-gh-actions-file? predicate

Check if the buffer matches the pattern .github/workflows/*.ya?ml.

LSP configuration

The gh-actions.ts-query-ls module exports a configuration for ts_query_ls server in order to register the custom is-gh-actions-file? predicate used by this plugin.

[!IMPORTANT] This is only needed if you will use the predicates defined by this plugin in your queries and you have set the valid_predicates setting for ts_query_ls.

---

[!NOTE] You can check my config for ts_query_ls for reference.

nvim-lspconfig + neovim < 0.11

[!IMPORTANT] Be sure to set gh-actions.nvim as a dependency

local lspconfig = require("lspconfig")
local gh_actions = require("gh-actions.ts-query-ls")

lspconfig.ts_query_ls.setup(vim.tbl_deep_extend("force", {
  -- your settings
}, gh_actions.expressions))

vim.lsp.config + neovim >= 0.11

[!IMPORTANT] Be sure to load gh-actions.nvim before

local gh_actions = require("gh-actions.ts-query-ls")

vim.lsp.config(
  "ts_query_ls",
  vim.tbl_deep_extend("force", {
    -- your settings
  }, gh_actions.expressions)
)
vim.lsp.enable("ts_query_ls")

after/lsp/ts_query_ls.lua + neovim >= 0.11

local gh_actions = require("gh-actions.ts-query-ls")

return vim.tbl_deep_extend("force", {
  -- your settings
}, gh_actions.expressions)

[!IMPORTANT] Be sure to load vim-map-side.nvim before calling vim.lsp.enable()

See LSP config merge

Then, in your init.lua:

vim.lsp.enable("ts_query_ls")

Troubleshooting

[!IMPORTANT] Be sure to run :checkhealth vim.treesitter and :checkhealth nvim-treesitter before checking the following errors.

Incompatible ABI version

If you found the following error:

- ERROR Parser "gh_actions_expressions" failed to load
  (path: .../gh_actions_expressions.so): ...: ABI version mismatch for
  .../gh_actions_expressions.so: supported between X and Y, found Z

[!NOTE] X and Y are the interval of ABI versions supported by neovim. Z is the ABI version that was used to develop the parser.

1. Install the following tools:

   • Node.js
   • tree-sitter cli

2. Run :TSInstallFromGrammar gh_actions_expressions to re-install the parser with the correct ABI version.

It's also recommended to add the from_grammar option to the setup of the gh-actions.tree-sitter module in order to avoid the need to run :TSInstallFromGrammar every time you update nvim-treesitter:

require("gh-actions.tree-sitter").setup({
  from_grammar = true,
})

Errors not related to neovim

Check the Troubleshooting section of tree-sitter-gh-actions-expressions.

Updates

This plugin will follow changes of tree-sitter-gh-actions-expressions:

• queries updates
• grammar updates