Package Exports

tree-sitter-gh-actions-expressions
tree-sitter-gh-actions-expressions/bindings/node/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (tree-sitter-gh-actions-expressions) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

tree-sitter-gh-actions-expressions

Tree-sitter grammar for Github Actions expressions

[!IMPORTANT] ABI version: 15

Parser requirements

gitignore (optional): for hashFiles() function
json (optional): for fromJSON() function
yaml: injection to its block_mapping_pair node. Check the yaml injection section for more information

Usage in Editors

Neovim

gh-actions.nvim: plugin that integrates this grammar to your Neovim configuration

Helix

WIP

Emacs

WIP

In General

You can get the built files from the release branch. If you have specific instructions for your editor, PR's are welcome.

Injection for `yaml` parser

Use the following query:

((block_mapping_pair
  key: (flow_node) @_key
  value: [
    (block_node
      (block_scalar) @_value)
    (flow_node
      [
        (plain_scalar
          (string_scalar) @_value)
        (double_quote_scalar) @_value
      ])
  ]
  (#lua-match? @_value "${{")) @injection.content
  (#is-gh-actions-file? "") ; NOTE: NEW PREDICATE
  (#set! injection.language "gh_actions_expressions")
  (#set! injection.include-children))

((block_mapping_pair
  key: (flow_node) @_key
  (#eq? @_key "if")
  value: (flow_node
    (plain_scalar
      (string_scalar) @_value)
    (#not-lua-match? @_value "${{"))) @injection.content
  (#is-gh-actions-file? "") ; NOTE: NEW PREDICATE
  (#set! injection.language "gh_actions_expressions")
  (#set! injection.include-children))

`is-gh-actions-file` predicate

To avoid injecting this grammar to files other than github actions, is recommended to create a predicate named is-gh-actions-file.

[!NOTE] The creation of this directive varies for each editor

This predicate will be the responsible to allow injection to files that matches the name pattern .github/workflows/*.ya?ml.

Implementations

gh-actions.nvim

Troubleshooting

AST errors within `bash` injections when using `run` key

AST error within bash injection

To avoid these errors, is recommended to surround the expression within a raw_string node, string with single quotes ', i.e.:

jobs:
  dry-run:
    name: dry-run
    runs-on: ubuntu-latest
    steps:
      - name: dry-run
        run: ./script.sh '${{ inputs.mode }}' --dry-run

Correct bash AST by using raw_string

What if I need it within a variable expansion?

AST error within variable expansion

Because variable expansion is done by using $ prefix, the ${{ and }} nodes will cause an AST error. To avoid this declare an auxiliary bash variable or an environment variable:

jobs:
  dry-run:
    name: dry-run
    runs-on: ubuntu-latest
    steps:
      - name: dry-run
        run: |
          auxiliary_var='${{ inputs.mode }}'
          ./script.sh "$MY_VAR and $MODE" --dry-run
          ./script.sh "$MY_VAR and $auxiliary_var" --dry-run
        env:
          MODE: ${{ inputs.mode }}

Correct bash AST by using auxiliary variables

References

Github Actions expressions documentation
if conditional:
- run.steps[*].if
- jobs.<job_id>.if
Gihub Actions Context documentation

Thanks

Thanks to @disrupted for creating tree-sitter-github-actions grammar, which is the base I used to create this grammar.