Skip to content

Latest commit

 

History

History
221 lines (140 loc) · 6.43 KB

actionlint.1.ronn

File metadata and controls

221 lines (140 loc) · 6.43 KB
Raw

actionlint(1) -- static checker for GitHub Actions workflow files

SYNOPSIS

actionlint []
actionlint [] ...
actionlint [] -

DESCRIPTION

actionlint is a linter for GitHub Actions workflow files.

Features:

  • Syntax check for workflow files to check unexpected or missing keys following workflow syntax
  • Strong type check for ${{ }} expressions to catch several semantic errors like access to not existing property, type mismatches, ...
  • Actions usage check to check that inputs at with: and outputs in steps.{id}.outputs are correct
  • shellcheck and pyflakes integrations for scripts at run:
  • Security checks; script injection by untrusted inputs, hard-coded credentials
  • Other several useful checks; glob syntax validation, dependencies check for needs:, runner label validation, cron syntax validation, ...

USAGE

To check all workflow files in the current repository, just run actionlint without arguments. It automatically finds the nearest .github/workflows directory:

$ actionlint

To check specific workflow files, pass the file paths as arguments:

$ actionlint file1.yaml file2.yaml

To check a content which is not saved in file yet (e.g. output from some command), pass - argument. It reads stdin and checks it as workflow file:

$ actionlint -

To serialize errors into JSON, use -format option. It allows to format error messages flexibly with Go template syntax.

$ actionlint -format '{{json .}}'

FLAGS

  • -color: Always enable colorful output. This is useful to force colorful outputs

  • -config-file : File path to config file

  • -debug: Enable debug output (for development)

  • -format : Custom template to format error messages in Go template syntax. See https://github.com/rhysd/actionlint/tree/main/docs/usage.md#format

  • -ignore : Regular expression matching to error messages you want to ignore. This flag is repeatable. For example, -ignore A -ignore B ignores errors whose message includes "A" OR "B".

  • -init-config: Generate default config file at .github/actionlint.yaml in current project

  • -no-color: Disable colorful output

  • -oneline: Use one line per one error. Useful for reading error messages from programs

  • -pyflakes : Command name or file path of "pyflakes" external command. If empty, pyflakes integration will be disabled (default "pyflakes")

  • -shellcheck : Command name or file path of "shellcheck" external command. If empty, shellcheck integration will be disabled (default "shellcheck")

  • -verbose: Enable verbose output

  • -stdin-filename : File name when reading input from stdin (default "<stdin>")

  • -version: Show version and how this binary was installed

  • -help, -h: Show help

DOCUMENTS

Documents for more details are available online.

Checks

https://github.com/rhysd/actionlint/tree/main/docs/checks.md

Full list of all checks done by actionlint with example inputs, outputs, and playground links.

Installation

https://github.com/rhysd/actionlint/tree/main/docs/install.md

Installation instructions. Prebuilt binaries, Homebrew package, building from source, a Docker image, a download script (for CI) are available.

Usage

https://github.com/rhysd/actionlint/tree/main/docs/usage.md

How to use actionlint command locally or on GitHub Actions, the online playground, an official Docker image, and integrations with reviewdog, Problem Matchers, super-linter, pre-commit.

Configuration

https://github.com/rhysd/actionlint/tree/main/docs/config.md

How to configure actionlint behavior. Currently only labels of self-hosted runners can be configured.

Go API

https://github.com/rhysd/actionlint/tree/main/docs/api.md

How to use actionlint as Go library.

References

https://github.com/rhysd/actionlint/tree/main/docs/reference.md

Links to resources.

USAGE ON GITHUB ACTIONS

Please try the download script.

https://github.com/rhysd/actionlint/blob/main/scripts/download-actionlint.bash

It downloads the latest version of actionlint executable to the current directory automatically. On GitHub Actions environment, it sets a file path to executable toexecutable output for using the executable in the following steps easily.

Here is an example of simple workflow to run actionlint on GitHub Actions. Please ensure shell: bash since the default shell for Windows runners is pwsh.

name: Lint GitHub Actions workflows
on: [push, pull_request]

jobs:
  actionlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download actionlint
        id: get_actionlint
        run: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
        shell: bash
      - name: Check workflow files
        run: ${{ steps.get_actionlint.outputs.executable }} -color
        shell: bash

or simply run

- name: Check workflow files
  run: |
    bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
    ./actionlint -color
  shell: bash

EXIT STATUS

actionlint command exits with one of the following exit statuses.

  • 0: It ran successfully and no problem was found.
  • 1: It ran successfully and some problem was found.
  • 2: It failed due to invalid command line option.
  • 3: It failed due to some fatal error.

PLAYGROUND

Thanks to WebAssembly, actionlint playground is available on your browser. It never sends any data to outside of the browser.

https://rhysd.github.io/actionlint/

Paste your workflow content to the code editor at left pane. It automatically shows the results at right pane. When editing the workflow content at the left pane, the results will be updated on the fly in the right pane. Clicking an error message in the results table moves a cursor to the position of the error in the code editor.

BUGS

Please visit issues page to see known bugs. If you found a new bug or have some feature request, please report by making a new issue.

https://github.com/rhysd/actionlint/issues

COPYRIGHT

actionlint is licensed under the MIT License: Copyright (c) 2021 rhysd

https://github.com/rhysd/actionlint/blob/main/LICENSE.txt