Skip to content

Demo

Clone and run

An example configuration file and .github directory structure can be found in the example directory of the repository. Use below commands to see octo-linter in action:

git clone https://github.com/mikolajgasior/octo-linter.git

docker build -t octo-linter .

cd octo-linter/example
docker run --platform=linux/amd64 --rm --name octo-linter \
  -v $(pwd)/dot-github:/dot-github \
  -v $(pwd):/config \
  octo-linter \
  lint -p /dot-github -l WARN -c /config/config.yml

Output

This should generate an output similar to the following:

level=ERROR msg="error downloading external action" workflow=workflow1.yaml step=0 uses=external-action/something@v2 err="error getting response from http request to action: external action was not found"
level=ERROR msg="error downloading external action" workflow=workflow1.yaml step=0 uses=external-action/something@v2 err="error getting response from http request to action: external action was not found"
level=ERROR msg="directory name must be dash-case" path=/dot-github/actions/InvalidActionName/action.yml rule=filenames__action_directory_name_format
level=ERROR msg="step 1 calls action 'actions/checkout@v4' that is not a valid local path" path=/dot-github/actions/InvalidActionName/action.yml rule=used_actions_in_action_steps__source
level=ERROR msg="step 1 calls action 'actions/checkout@v4' that is not a valid local path" path=/dot-github/actions/InvalidActionName/action.yml rule=used_actions_in_action_steps__source
level=ERROR msg="step 2 env 'InvalidEnvName' must be ALL_CAPS" path=/dot-github/actions/some-action/action.yml rule=naming_conventions__action_step_env_format
(...)

Use -m flag to print each error message attributes on a separate line.

level=ERROR
msg="error downloading external action"
workflow="workflow1.yaml"
step="0"
uses="external-action/something@v2"
err="error getting response from http request to action: external action was not found"
---
level=ERROR
msg="error downloading external action"
workflow="workflow1.yaml"
step="0"
uses="external-action/something@v2"
err="error getting response from http request to action: external action was not found"
---
level=ERROR
msg="file extension must be one of: yml"
path="/dot-github/actions/InvalidActionExtension/action.yaml"
rule="filenames__action_filename_extensions_allowed"
---
(...)

Markdown summary

octo-linter can generate a simple summary in Markdown format that can be posted as a comment to a pull request. Create a directory, for example output, and add --output output (-o) flag to the command to generate an output.md file inside of it.

Markdown can be limited to print out only certain amount of errors. This can be set with --output-errors (-u) flag.

Please see modified code below:

mkdir output

docker run --platform=linux/amd64 --rm --name octo-linter \
  -v $(pwd)/dot-github:/dot-github \
  -v $(pwd):/config \
  -v $(pwd)/output:/output \
  octo-linter \
  lint -p /dot-github -l WARN -c /config/config.yml -o /output -u 5

Screenshot of generated Markdown file

output.md

Exit code

Tool exits with exit code 0 when everything is fine. 1 when there are errors, 2 when there are only warnings. Additionally it may exit with a different code, eg. 22. These numbers indicate another error whilst reading files.

Checking secrets and vars

octo-linter can scan the code for secrets and variables and compare them with file containing list of defined one. If there is any secret or var that is not on the list, tool will output info about it. See below run and its output.

docker run --platform=linux/amd64 --rm --name octo-linter \
  -v $(pwd)/dot-github:/dot-github \
  -v $(pwd):/config \
  octo-linter \
  lint -p /dot-github -l WARN -c /config/config.yml \
  -s /config/secrets_list.txt \
  -z /config/vars_list.txt \
  2>&1 | grep NON_EXISTING_ONE
level=ERROR msg="workflow_called_variable_exists_in_file: workflow 'workflow1.yaml' calls a variable 'NON_EXISTING_ONE' that does not exist in the vars file"
level=ERROR msg="workflow_called_variable_exists_in_file: workflow 'workflow1.yaml' calls a secret 'NON_EXISTING_ONE' that does not exist in the secrets file"