https://github.com/hdoc1509/gh-actions.nvim
Plugins that improves support for Github Actions files in Neovim.
https://github.com/hdoc1509/gh-actions.nvim
github-actions neovim neovim-plugin parser tree-sitter tree-sitter-gh-actions-expressions
Last synced: about 2 months ago
JSON representation
Plugins that improves support for Github Actions files in Neovim.
- Host: GitHub
- URL: https://github.com/hdoc1509/gh-actions.nvim
- Owner: Hdoc1509
- License: apache-2.0
- Created: 2025-09-26T03:18:27.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-09-27T04:23:50.000Z (9 months ago)
- Last Synced: 2025-09-27T06:14:39.857Z (9 months ago)
- Topics: github-actions, neovim, neovim-plugin, parser, tree-sitter, tree-sitter-gh-actions-expressions
- Homepage:
- Size: 8.79 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gh-actions.nvim
Plugin that improves support for [Github Actions][gh-actions-docs] files
in Neovim.
## Features
- Syntax highlighting for Github Actions expressions thanks to
[`tree-sitter-gh-actions-expressions`][ts-gh-actions-expressions]. Compatible
with [`^0.3.0`][ts-gh-actions-expressions-version]
- [New predicate](#is-gh-actions-file-predicate) with its [LSP
configuration](#lsp-configuration)
## Requirements
- `Neovim >= 0.9.0`
- [`nvim-treesitter`][nvim-treesitter]
- [`gitignore` parser][gitignore] (optional): for `hashFiles()` function
- [`json` parser][json] (optional): for `fromJSON()` function
- [`yaml` parser][yaml]: injection to its `block_mapping_pair` node
## Install
Installation examples for [`lazy.nvim`](https://github.com/folke/lazy.nvim) and
[`packer.nvim`](https://github.com/wbthomason/packer.nvim):
> [!IMPORTANT]
> This snippet is for neovim >= 0.11.0
```lua
{
"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`][nvim-ts-main-ensure-install] branch
> [!IMPORTANT]
> This snippet is for neovim >= 0.11.0. See [Minit README](./minit/README.md#nvim-ts-main-ensure-installlua)
> for some details about possible compatibility for neovim 0.10.
Installation example
Use `install` module instead:
```lua
{
"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`][nvim-ts-master] branch
> [!IMPORTANT]
> This snippet is for neovim >= 0.9.0.
Installation example
```lua
{
"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
Default configuration
```lua
---@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`][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`](https://github.com/ribru17/ts_query_ls#valid_predicates).
---
> [!NOTE]
> You can check [my config for `ts_query_ls`][nvim-config-ts-query-ls] for
> reference.
### [nvim-lspconfig][lspconfig] + neovim < 0.11
> [!IMPORTANT]
> Be sure to set `gh-actions.nvim` as a dependency
```lua
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][vim-lsp-config] + neovim >= 0.11
> [!IMPORTANT]
> Be sure to load `gh-actions.nvim` before
```lua
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
```lua
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](https://neovim.io/doc/user/lsp.html#lsp-config-merge)
Then, in your `init.lua`:
```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:
```checkhealth
- 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`][nodejs]
- [`tree-sitter cli`][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`:
```lua
require("gh-actions.tree-sitter").setup({
from_grammar = true,
})
```
### Errors not related to neovim
Check the [Troubleshooting section of
`tree-sitter-gh-actions-expressions`][ts-gh-actions-expressions-troubleshooting].
## Updates
This plugin will follow changes of `tree-sitter-gh-actions-expressions`:
- [`queries`][ts-gh-actions-expressions-queries] updates
- [`grammar`][ts-gh-actions-expressions-grammar] updates
[ts-gh-actions-expressions]: https://github.com/hdoc1509/tree-sitter-gh-actions-expressions
[ts-gh-actions-expressions-grammar]: https://github.com/hdoc1509/tree-sitter-gh-actions-expressions/tree/master/grammar.js
[ts-gh-actions-expressions-queries]: https://github.com/hdoc1509/tree-sitter-gh-actions-expressions/tree/master/queries
[ts-gh-actions-expressions-version]: https://github.com/Hdoc1509/tree-sitter-gh-actions-expressions/blob/master/CHANGELOG.md#030
[ts-gh-actions-expressions-troubleshooting]: https://github.com/Hdoc1509/tree-sitter-gh-actions-expressions#troubleshooting
[gitignore]: https://github.com/shunsambongi/tree-sitter-gitignore
[json]: https://github.com/tree-sitter/tree-sitter-json
[yaml]: https://github.com/tree-sitter-grammars/tree-sitter-yaml
[nvim-treesitter]: https://github.com/nvim-treesitter/nvim-treesitter
[nvim-ts-main-ensure-install]: https://github.com/nvim-treesitter/nvim-treesitter/tree/0bb981c87604200df6c8fb81e5a411101bdf93af#setup
[nvim-ts-master]: https://github.com/nvim-treesitter/nvim-treesitter/tree/master
[nodejs]: https://nodejs.org/en/download
[tree-sitter-cli]: https://github.com/tree-sitter/tree-sitter/tree/master/crates/cli
[lspconfig]: (https://github.com/neovim/nvim-lspconfig)
[gh-actions-docs]: https://docs.github.com/en/actions/reference/workflows-and-actions
[vim-lsp-config]: https://neovim.io/doc/user/lsp.html#lsp-config
[nvim-config-ts-query-ls]: https://github.com/Hdoc1509/nvim-config/blob/master/lua/plugins/lsp/servers/ts_query_ls/init.lua
[ts-query-ls]: https://github.com/ribru17/ts_query_ls