# @actions/languageserver

> Language server for GitHub Actions

Latest version **0.3.61** (published 2026-08-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @actions/languageserver
pnpm add @actions/languageserver
yarn add @actions/languageserver
bun add @actions/languageserver
```

Provides the command `actions-languageserver`.

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.61 |
| Published | 2026-08-04 |
| First published | 2023-03-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >= 20 |
| Dependencies | 7 |
| Unpacked size | 2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 195 |
| Maintainers | thboop, ericsciple, bdehamer |

## Links

- npm: https://www.npmjs.com/package/@actions/languageserver
- Repository: https://github.com/actions/languageservices
- Homepage: https://github.com/actions/languageservices#readme
- Issues: https://github.com/actions/languageservices/issues
- npm.io page: https://npm.io/package/@actions/languageserver

## Dependencies (7)

- [yaml](https://npm.io/package/yaml.md) ^2.1.3
- [@octokit/rest](https://npm.io/package/@octokit/rest.md) ^21.1.1
- [@octokit/types](https://npm.io/package/@octokit/types.md) ^9.0.0
- [vscode-languageserver](https://npm.io/package/vscode-languageserver.md) ^8.0.2
- [@actions/languageservice](https://npm.io/package/@actions/languageservice.md) ^0.3.61
- [@actions/workflow-parser](https://npm.io/package/@actions/workflow-parser.md) ^0.3.61
- [vscode-languageserver-textdocument](https://npm.io/package/vscode-languageserver-textdocument.md) ^1.0.7

## Recent versions

- 0.3.61 (latest) — 2026-08-04
- 0.3.60 — 2026-07-15
- 0.3.59 — 2026-07-13
- 0.3.58 — 2026-06-11
- 0.3.57 — 2026-05-12
- 0.3.56 — 2026-05-08
- 0.3.55 — 2026-04-28
- 0.3.54 — 2026-04-21
- 0.3.53 — 2026-04-15
- 0.3.52 — 2026-04-14
- 0.3.51 — 2026-04-03
- 0.3.50 — 2026-04-01
- 0.3.49 — 2026-03-20
- 0.3.48 — 2026-03-18
- 0.3.47 — 2026-03-10
- … 48 more at https://npm.io/package/@actions/languageserver/versions

## README

# actions/languageserver

`actions-languageserver` hosts the `actions-languageservice` and makes it available via the [language server protocol](https://microsoft.github.io/language-server-protocol/) (LSP) as a standalone language server.

## Installation

The [package](https://www.npmjs.com/package/@actions/languageserver) contains TypeScript types and compiled ECMAScript modules.

```bash
npm install @actions/languageserver
```

To install the language server as a standalone CLI:

```bash
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`:

```typescript
import "@actions/languageserver";
```

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

`client.ts`:

```typescript
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](../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.

```typescript
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:

```typescript
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.

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

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

**Available experimental features:**

| Feature | Description |
|---------|-------------|
| `missingInputsQuickfix` | Code action to add missing required inputs for actions |
| `blockScalarChompingWarning` | Warn when block scalars (`\|` or `>`) use implicit clip chomping, which adds a trailing newline that may be unintentional |
| `allowBackgroundSteps` | Enable background workflow steps and related wait/cancel steps |

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:

```bash
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

```bash
npm install -g @actions/languageserver
```

#### 2. Set up filetype detection

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

```lua
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`:

```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: git@github.com: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`:

```lua
vim.lsp.enable('actionsls')
```

#### 5. Verify it's working

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

```vim
:checkhealth vim.lsp
```

You should see `actionsls` in the list of attached clients.

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.

If you do want to contribute, please run [prettier](https://prettier.io/) to format your code and add unit tests as appropriate before submitting your PR.

### Build

```bash
npm run build
```

or to watch for changes

```bash
npm run watch
```

### Running the language server locally

After running

```bash
npm run build:cli
npm link
```

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

```bash
actions-languageserver --stdio
```

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

```bash
npm run watch:cli
```

### Test

```bash
npm test
```

or to watch for changes and run tests:

```bash
npm run test-watch
```

### Lint

```bash
npm run format-check
```

## License

This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms.

---
_Source: https://npm.io/package/@actions/languageserver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
