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

## SYNOPSIS

`actionlint` [<flags>] <br>
`actionlint` [<flags>] <file>...<br>
`actionlint` [<flags>] -<br>


## 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` <PATH>:
    File path to config file

  * `-debug`:
    Enable debug output (for development)

  * `-format` <FORMAT>:
    Custom template to format error messages in Go template syntax. See the usage documentation
    for more details.

  * `-ignore` <PATTERN>:
    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` <EXECUTABLE>:
    Command name or file path of "pyflakes" external command. If empty, pyflakes integration will be
    disabled (default "pyflakes")

  * `-shellcheck` <EXECUTABLE>:
    Command name or file path of "shellcheck" external command. If empty, shellcheck integration will
    be disabled (default "shellcheck")

  * `-verbose`:
    Enable verbose output

  * `-stdin-filename` <NAME>:
    File name when reading input from stdin (default "&lt;stdin&gt;")

  * `-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/blob/v1.7.12/docs/checks.md

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

### Installation

https://github.com/rhysd/actionlint/blob/v1.7.12/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/blob/v1.7.12/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/blob/v1.7.12/docs/config.md

How to configure actionlint behavior by the configuration file `actionlint.yaml`.

### Go API

https://github.com/rhysd/actionlint/blob/v1.7.12/docs/api.md

How to use actionlint as Go library.

### References

https://github.com/rhysd/actionlint/blob/v1.7.12/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 to`executable` 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

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

<!-- vim: set ft=markdown: -->
