# @actions/languageservice

> Language service for GitHub Actions

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

## Install

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

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.61 |
| Published | 2026-08-04 |
| First published | 2023-03-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >= 20 |
| Dependencies | 6 |
| Unpacked size | 1.1 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/languageservice
- 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/languageservice

## Dependencies (6)

- [yaml](https://npm.io/package/yaml.md) ^2.1.1
- [vscode-uri](https://npm.io/package/vscode-uri.md) ^3.0.8
- [@actions/expressions](https://npm.io/package/@actions/expressions.md) ^0.3.61
- [@actions/workflow-parser](https://npm.io/package/@actions/workflow-parser.md) ^0.3.61
- [vscode-languageserver-types](https://npm.io/package/vscode-languageserver-types.md) ^3.17.2
- [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/languageservice/versions

## README

# actions/languageservice

This package contains the logic for the GitHub Actions workflows language server.

## Installation

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

```bash
npm install @actions/languageservice
```

## Usage

### Basic usage

#### Concepts

The language service features use three sources of information:

* a built-in static schema for the workflow YAML file
* _value providers_ which can dynamically add values to the schema, for example, the list of available labels for a repository when validating `runs-on`.
* _context providers_ which can dynamically provide available contexts used in [expressions](https://docs.github.com/actions/reference/context-and-expression-syntax-for-github-actions#about-contexts-and-expressions). For example, the contents of the `github.event` context for a given workflow file.

#### Validation

Validate a workflow file, returns an array of [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic) objects.

```typescript
const config: ValidationConfig = {
  valueProviderConfig: valueProviders(sessionToken, repoContext, cache),
  contextProviderConfig: contextProviders(sessionToken, repoContext, cache),
};

const result = await validate(textDocument, config); // result is an array of `Diagnostic`
```

#### Hover

Get information when [hovering](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_hover) over a token in the workflow file.

```typescript
import {hover} from "@actions/languageservice";

const document = {
  uri: "file:///path/to/file",
  getText: () => "on: push\n  jobs:\n    build:\n      runs-on: ubuntu-latest\n      steps:\n        - run: echo hello"
};

const hover = await hover(document, {line: 0, character: 1}); // { contents: { kind: "markdown", value: "The event that triggers the workflow" } }
```

#### Auto-completion

```typescript
import {complete} from "@actions/languageservice";

const document = {
  uri: "file:///path/to/file",
  getText: () => `on: 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - run: echo hello`
};

// Trigger completion for `on: |`
const suggestions = await complete(document, {line: 0, character: 4});
```

will return

```jsonc
[{
  "documentation": {
    "kind": "markdown",
    "value": "Runs your workflow when branch protection rules in the workflow repository are changed.",
  },
  "label": "branch_protection_rule",
  "textEdit": {
    "newText": "branch_protection_rule",
    "range": {
      "end": {"character": 4, "line": 0,},
      "start": {"character": 4, "line": 0},
    },
  },
},
//... other events
]
```

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

### 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/languageservice · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
