actions/languageserver

actions-languageserver hosts the actions-languageservice and makes it available via the language server protocol (LSP) as a standalone language server.

Installation

The package contains TypeScript types and compiled ECMAScript modules.

npm install @actions/languageserver

To install the language server as a standalone CLI:

npm install -g @actions/languageserver

This makes the actions-languageserver command available globally.

Usage

Basic usage using vscode-languageserver-node

For the server, import the module. It detects whether it's running in a Node.js environment or a web worker and initializes the appropriate connection.

server.ts:

import "@actions/languageserver";

For the client, create a new LanguageClient pointing to the server module.

client.ts:

import {LanguageClient, ServerOptions, TransportKind} from "vscode-languageclient/node";

const debugOptions = {execArgv: ["--nolazy", "--inspect=6010"]};

const clientOptions: LanguageClientOptions = {
  documentSelector: [{
    pattern: "**/.github/workflows/*.{yaml,yml}"
  }]
};

const serverModule = context.asAbsolutePath(path.join("dist", "server.js"));
const serverOptions: ServerOptions = {
  run: {module: serverModule, transport: TransportKind.ipc},
  debug: {
    module: serverModule,
    transport: TransportKind.ipc,
    options: debugOptions
  }
};

const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);

From a web worker

See ../browser-playground for an example implementation that hosts the language server in a web worker.

Providing advanced functionality

The language server accepts initialization options that can be used to configure additional functionality. If you pass in a github.com sessionToken, the language service will use data from github.com to perform additional validations and provide additional auto-completion suggestions.

export interface InitializationOptions {
  /**
   * GitHub token that will be used to retrieve additional information from github.com
   *
   * Requires the `repo` and `workflow` scopes
   */
  sessionToken?: string;

  /**
   * List of repositories that the language server should be aware of
   */
  repos?: RepositoryContext[];

  /**
   * Desired log level
   */
  logLevel?: LogLevel;

  /**
   * Experimental features that are opt-in
   */
  experimentalFeatures?: ExperimentalFeatures;
}

pass the initializationOptions to the LanguageClient when establishing the connection:

const clientOptions: LanguageClientOptions = {
  documentSelector: [{
    pattern: "**/.github/workflows/*.{yaml,yml}"
  }],
  initializationOptions: initializationOptions
};

const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);

Experimental Features

The language server supports opt-in experimental features via the experimentalFeatures initialization option. These features may change or be removed in between releases.

initializationOptions: {
  experimentalFeatures: {
    // Enable all experimental features
    all: true,

    // Or enable specific features
    missingInputsQuickfix: true,
  }
}

Available experimental features:

Individual feature flags take precedence over all. For example, { all: true, missingInputsQuickfix: false } enables all experimental features except missingInputsQuickfix.

When a feature graduates to stable, its flag becomes a no-op and the feature will be enabled regardless of the configuration value.

Standalone CLI

After installing globally, you can run the language server directly:

actions-languageserver --stdio

This starts the language server using stdio transport, which is the standard way for editors to communicate with language servers.

In Neovim

1. Install the language server

npm install -g @actions/languageserver

2. Set up filetype detection

Add this to your init.lua to detect GitHub Actions workflow files:

vim.filetype.add({
  pattern = {
    [".*/%.github/workflows/.*%.ya?ml"] = "yaml.ghactions",
  },
})

This sets the filetype to yaml.ghactions for YAML files in .github/workflows/, allowing you to keep separate YAML LSP configurations if needed.

3. Create the LSP configuration

As of Neovim 0.11+ you can add this configuration in ~/.config/nvim/lsp/actionsls.lua:

local function get_github_token()
  local handle = io.popen("gh auth token 2>/dev/null")
  if not handle then return nil end
  local token = handle: read("*a"):gsub("%s+", "")
  handle:close()
  return token ~= "" and token or nil
end

local function parse_github_remote(url)
  if not url or url == "" then return nil end

  -- SSH format: [email protected]:owner/repo.git
  local owner, repo = url:match("git@github%.com:([^/]+)/([^/%.]+)")
  if owner and repo then
    return owner, repo: gsub("%.git$", "")
  end

  -- HTTPS format: https://github.com/owner/repo.git
  owner, repo = url:match("github%.com/([^/]+)/([^/%.]+)")
  if owner and repo then
    return owner, repo:gsub("%.git$", "")
  end

  return nil
end

local function get_repo_info(owner, repo)
  local cmd = string.format(
    "gh repo view %s/%s --json id,owner --template '{{.id}}\t{{.owner.type}}' 2>/dev/null",
    owner,
    repo
  )
  local handle = io.popen(cmd)
  if not handle then return nil end
  local result = handle: read("*a"):gsub("%s+$", "")
  handle:close()

  local id, owner_type = result:match("^(%d+)\t(.+)$")
  if id then
    return {
      id = tonumber(id),
      organizationOwned = owner_type == "Organization",
    }
  end
  return nil
end

local function get_repos_config()
  local handle = io.popen("git rev-parse --show-toplevel 2>/dev/null")
  if not handle then return nil end
  local git_root = handle: read("*a"):gsub("%s+", "")
  handle:close()

  if git_root == "" then return nil end

  handle = io.popen("git remote get-url origin 2>/dev/null")
  if not handle then return nil end
  local remote_url = handle:read("*a"):gsub("%s+", "")
  handle:close()

  local owner, name = parse_github_remote(remote_url)
  if not owner or not name then return nil end

  local info = get_repo_info(owner, name)

  return {
    {
      id = info and info.id or 0,
      owner = owner,
      name = name,
      organizationOwned = info and info.organizationOwned or false,
      workspaceUri = "file://" .. git_root,
    },
  }
end

return {
  cmd = { "actions-languageserver", "--stdio" },
  filetypes = { "yaml.ghactions" },

  -- `root_dir` ensures that the LSP does not attach to all yaml files
  root_dir = function(bufnr, on_dir)
    local parent = vim.fs.dirname(vim.api.nvim_buf_get_name(bufnr))
    if
      vim.endswith(parent, '/.github/workflows')
      or vim.endswith(parent, '/.forgejo/workflows')
      or vim.endswith(parent, '/.gitea/workflows')
    then
      on_dir(parent)
    end
  end,

  init_options = {
    -- Optional: provide a GitHub token and repo context for added functionality
    -- (e.g., repository-specific completions)
    sessionToken = get_github_token(),
    repos = get_repos_config(),
  },

  -- allow the lsp to register capabilities on demand
  capabilities = {
    workspace = {
      didChangeWorkspaceFolders = {
        dynamicRegistration = true,
      },
    },
  },

  -- given a file:// protocol path as built using the workspaceUri above,
  -- resolve path to disk path and provide filecontents when lsp requests this
  -- action https://github.com/actions/languageservices/blob/main/languageserver/src/request.ts#L2
  -- taken from https://github.com/neovim/nvim-lspconfig/blob/75e49cfa588a89ca667d767c0afef3ceac205faa/lsp/gh_actions_ls.lua#L33-L48
  handlers = {
    ["actions/readFile"] = function(_, result)
      if type(result.path) ~= "string" then
        return nil, nil
      end
      local file_path = vim.uri_to_fname(result.path)
      if vim.fn.filereadable(file_path) == 1 then
        local f = assert(io.open(file_path, "r"))
        local text = f:read("*a")
        f:close()

        return text, nil
      end
      return nil, nil
    end,
  },
}

4. Enable the LSP

Add to your init.lua:

vim.lsp.enable('actionsls')

5. Verify it's working

Open any .github/workflows/*.yml file and run:

:checkhealth vim.lsp

You should see actionsls in the list of attached clients.

Contributing

See CONTRIBUTING.md at the root of the repository for general guidelines and recommendations.

If you do want to contribute, please run prettier to format your code and add unit tests as appropriate before submitting your PR.

Build

npm run build

or to watch for changes

npm run watch

Running the language server locally

After running

npm run build:cli
npm link

actions-languageserver will be available globally. You can start it with:

actions-languageserver --stdio

Once linked you can also watch for changes and rebuild automatically:

npm run watch:cli

Test

npm test

or to watch for changes and run tests:

npm run test-watch

Lint

npm run format-check

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.