shellcheck-gha

此Python脚本从GitHub workflows（`jobs.<job_id>.steps[*].run`）中提取shell脚本，并对其运行ShellCheck。

• shellcheck-gha
  • 安装
    • 使用GitHub Actions（推荐）
    • PyPI
    • 从源
  • 用法
  • 示例
  • 目标
  • 非目标

安装

需求

• Python ≥ 3.11
• ShellCheck ≥ 0.9.0，可在apt、brew、cabal、dnf和pkg上使用。

使用GitHub Actions（推荐）

可以将shellcheck-gha项目用作GitHub Workflow步骤

on:
  push:
    paths:
      - .github/**
  pull_request:
    paths:
      - .github/**

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run ShellCheck
        uses: saleor/shellcheck-gha@v0
        # Uncomment to customize the scan directory:
        # with:
        #   scan-directory-path: .github/

[!重要]
默认情况下，只有 ./.github 目录会被扫描（递归）。如果某些 GitHub 组合操作定义在 .github 目录之外，请考虑通过修改 scan-directory-path 参数来添加步骤以扫描额外的目录。

PyPI

项目托管在 PyPI 上，网址为 https://pypi.ac.cn/project/shellcheck-gha/。要安装项目，请运行

$ pip install shellcheck-gha

从源

或者，可以使用 poetry 克隆并安装项目。

$ git clone https://github.com/saleor/shellcheck-gha
$ pip install poetry
$ poetry install
$ shellcheck-gha --help

用法

$ shellcheck-gha --help
usage: shellcheck-gha [-h] [--default-shell DEFAULT_SHELL] [--verbose] [--debug] [--skip-unknown-files | --no-skip-unknown-files] [directory]

positional arguments:
  directory

options:
  -h, --help            show this help message and exit
  --default-shell DEFAULT_SHELL
                        The default shell running in the workflow(s)
  --verbose             Show more details about the execution.
  --debug               Add debug information (takes precedence over --verbose).
  --skip-unknown-files, --no-skip-unknown-files
                        Whether to exit with an error on when parsing non-GitHub workflow or composite action YAML files. Skipping is useful when a directory
                        may be mixed with other YAML files (e.g. config files such as .github/dependabot.yaml). Unknown files are skipped by default.

示例

$ shellcheck-gha .
=== Results: 2 file(s) have findings ===
Scanned 5 files (16 shell scripts)
[INFO] In bad.yaml:
    Message: Double quote to prevent globbing and word splitting.
    More information: https://www.shellcheck.net/wiki/SC2086
    Code:
        test $USE_GITIGNORE == true
             ^^^^^^^^^^^^^^^
[INFO] In tests/sample_workflows/with-findings.yaml:
    Message: Double quote to prevent globbing and word splitting.
    More information: https://www.shellcheck.net/wiki/SC2086
    Code:
        echo $BAD_JOB1
             ^^^^^^^^^^
[INFO] In tests/sample_workflows/with-findings.yaml:
    Message: Double quote to prevent globbing and word splitting.
    More information: https://www.shellcheck.net/wiki/SC2086
    Code:
        echo $BAD_JOB2
             ^^^^^^^^^^

目标

• 仅检查与 *nix 相关的 shell（sh、bash、ksh）
• 提供有用的日志，使用户能够快速找到他们工作流程中的问题代码。

非目标

• 差异检查（基础提交与头提交）
• 对 GitHub 工作流程的逻辑理解，例如（但不限于）
  • 处理 defaults.run.shell
  • 支持字符串插值（${{ ... }}）
• 追踪发现的确切位置（行号、列）