原帖于freecodecamp.org

当您开始一个新项目时,您可能必须添加多个 linting 工具来美化您的代码并防止简单的错误。

您经常会使用多个 linter——其中一个可能支持 npm 安装,另一个可能支持 PyPI 安装,依此类推。您还需要在 CI 中设置一些自动化来运行这些 linter,但是这个过程非常繁琐😫。

在本文中,我将向您展示如何使用 GitHub Super Linter,一个单一的 linter 来解决所有这些问题。我的大部分个人项目也使用 GitHub Super Linter,我个人发现它是一个巨大的救星。

为什么需要 Linting?

Linting 本质上是一种静态代码分析。它会根据一些规则分析您编写的代码是否存在风格或程序错误。将其视为一种标记软件中可疑使用的工具。

linter 可以通过以下方式帮助您节省大量时间:

• 防止断码被推送

• 帮助建立编码最佳实践

• 代码布局和格式的构建指南

• 帮助代码审查更加顺畅

• 从语法错误中标记代码中的错误

鉴于 linting 工具的有用性质,理想情况下,您希望在对推送到存储库的每段代码进行任何代码审查之前运行一个 linter。这绝对可以帮助您编写更好、更易读、更稳定的代码。

这是一个使用Black的示例,这是一个专注于代码格式化的 Python linting 工具。

Black 所做的格式更改

GitHub Super Linter 可以帮助您轻松高效地将这些功能引入您的项目。 GitHub Super Linter 是多个常用 linter 的组合,您可以非常轻松地使用它们。它允许您为这些 linter 设置自动运行,以及在单个项目中管理多个 linter!

还有大量带有环境变量的自定义功能,可以帮助您将 Super Linter 自定义到您的个人存储库。

如何在 GitHub Actions 中使用 GitHub Super Linter

Super Linter 主要设计为在 GitHub Action 中运行,这也是我使用它很长一段时间的方式。我们将首先讨论这个。接下来,您应该在您的存储库中创建一个新的 GitHub 操作。让我们在.github/workflows/linter.yml创建一个新文件。

展望未来,我假设您了解 GitHub Actions 的基本语法。但如果您不需要或需要快速复习,我建议您阅读此快速入门指南。

如何创建动作

我们已经有一个空白文件.github/workflows/linter.yml,我们现在将使用一个操作来填充它,您可以使用它来对您的项目进行 lint。

我们将首先为我们的操作命名。这是 GitHub 操作状态检查下显示的内容:

name: Lint Code Base

接下来,让我们为我们的操作指定触发器。这回答了何时应该对代码库进行 lint 的问题。在这里,我们告诉它在每次推送和每次拉取请求时运行 lint。

name: Lint Code Base

on: [push, pull_request]

这是触发器的另一个非常常用的配置。这仅在您向main或master分支发出拉取请求时运行,而不是在推送到这些分支时运行。

on:
  push:
    branches-ignore: [master, main]
  pull_request:
    branches: [master, main]

接下来,我们要设置一个工作。您放入单个作业中的所有组件都将按顺序运行。在这里,将其视为步骤以及我们希望它们在触发器满足时运行的顺序。

我们将这项工作命名为“Lint Code Base”,并要求 GitHub 在 GitHub 支持的 Ubuntu 最新版本的运行器上运行我们的工作。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

您不必像我们在这里那样使用单一类型的跑步者(ubuntu-latest)。拥有代理种类矩阵是一种常见的做法,但在这种情况下,它将在所有种类的跑步者上以相同的方式运行。您经常使用运行器矩阵来测试您的代码是否在各种平台上运行良好。

GitHub Super Linter 在其他机器类型上的工作方式没有任何不同,因此我们只使用单一机器类型。

接下来,我们将开始定义我们希望此工作流具有的步骤。我们基本上有两个步骤:

1. 签出代码

2. 运行超级 linter

继续检查代码。为此,我们将使用 GitHub 的官方结帐操作。

我们将设置fetch-depth: 0以获取所有分支和标签的所有历史记录,这是 Super linter 获取更改文件的正确列表所需的。如果您没有这样做,则只会获取一个提交。

我们还为我们的步骤命名,并告诉它我们要使用 GitHub 存储库actions/checkout@v3中存在的操作。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

这段代码检查您在$GITHUB_WORKSPACE下的存储库,这允许工作流的其余部分访问此存储库。我们正在检查的存储库是您的代码所在的存储库,最好是同一个存储库。

如何运行 Linter

现在我们将添加运行 linter 的步骤,因为我们已经检查了我们的代码。您可以在运行操作时使用环境变量自定义 GitHub Super Linter。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Lint Code Base
        uses: github/super-linter@v4

我们现在将讨论您经常与 GitHub Super Linter 一起使用的环境变量以及一些示例。

• VALIDATE_ALL_CODEBASE:这决定了 Super Linter 是应该对整个代码库进行 lint,还是只对该提交引入的更改进行 lint。这些更改是使用git diff发现的,但您也可以更改搜索算法(但我们不会在本文中对此进行研究)。示例:VALIDATE_ALL_CODEBASE: true。

• GITHUB_TOKEN:顾名思义,这是GitHub令牌的值。如果你使用它,GitHub 将显示你使用的每个 linter(我们将很快看到如何做到这一点)作为 UI 上的单独检查。示例:在 GitHub Actions 中,您可以使用GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}。

• DEFAULT_BRANCH:存储库默认分支的名称。示例:DEFAULT_BRANCH: main。

• IGNORE_GENERATED_FILES:如果您有任何工具生成的文件,您可以将它们标记为@generated。如果此环境变量设置为 true,Super Linter 将忽略这些文件。示例:IGNORE_GENERATED_FILES: true。

• IGNORE_GITIGNORED_FILES:从 linting 中排除.gitignore中的文件。示例:IGNORE_GITIGNORED_FILES: true。

• LINTER_RULES_PATH:任何 linter 自定义文件应该在的自定义路径。默认情况下,您的文件应位于.github/linters/。示例:LINTER_RULES_PATH: /.

这些是您最常使用的一些环境变量,但我们讨论过的还没有一个讨论特定于语言的 linting。

如果您不使用我们讨论的任何环境变量,Super Linter 会自动为您的代码库查找并使用所有适用的 linter。

如何将特定的 Linter 添加到 Super Linter

您通常只会对为您的项目使用特定的 linter 感兴趣。您可以使用以下环境变量模式来添加您想要的任何 linter:

VALIDATE_{LANGUAGE}_{LINTER}

您可以在支持的 Linter 列表中找到它们的命名约定。

这里有几个例子,我们指定要使用 Black 对所有 Python 文件进行 lint,对 JavaScript 文件使用 ESLint,对 HTML 文件使用 HTMLHint。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Lint Code Base
        uses: github/super-linter@v4

      - name: Lint Code Base
        uses: github/super-linter@v4
        env:
          VALIDATE_ALL_CODEBASE: true
          VALIDATE_JAVASCRIPT_ES: true
          VALIDATE_PYTHON_BLACK: true
          VALIDATE_HTML: true
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

一旦将其中一个 linter 设置为true,所有其他 linter 将不会运行。在上面的代码片段中,除了 ESLint、Black 或 HTMLHint 之外的所有 linter 都不会运行。

然而,在这个例子中,我们将一个 linter 设置为false,所以除了 ESLint 之外的每个 linter 都将在这里运行:

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Lint Code Base
        uses: github/super-linter@v4

      - name: Lint Code Base
        uses: github/super-linter@v4
        env:
          VALIDATE_ALL_CODEBASE: true
          VALIDATE_JAVASCRIPT_ES: false
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

如何自定义 Lint 检查

Linter 通常使用配置文件,因此您可以修改 linter 使用的规则。在上面我展示的两个完整示例中,Super Linter 将尝试查找.github/linters/下的任何配置文件。

这些可能是用于配置 ESLint 的.eslintrc.yml文件,用于配置 HTMLHint 的.htmlhintrc等。

如果您使用 Python 的 Flake8 linter,以下是配置文件的示例:

[flake8]
max-line-length = 120

你把它保存在.github/linters/.flake8。然后,您将在运行 Flake8 linter 时使用它。您可以在此处找到可以使用的模板配置文件示例。

但是,这里有两个示例说明如何修改此路径:

1. 你所有的 linter 配置文件都在其他目录中

将目录路径添加为环境变量,如下所示:

LINTER_RULES_PATH: configs/

1.添加配置文件的路径

您还可以将特定 linter 的路径硬编码为环境变量。这是一个例子:

JAVASCRIPT_ES_CONFIG_FILE: configs/linters/.eslintrc.yml

如何在 GitHub Actions 之外运行 Super Linter

GitHub Super Linter 是为在 GitHub Actions 中运行而构建的。但是在本地或其他 CI 平台上运行它可能特别有用。您基本上将像在任何其他 CI 平台上本地一样运行 Super Linter。

如何在本地运行 Super Linter

您首先要使用以下命令从 DockerHub 拉取最新的 Docker 容器:

docker pull github/super-linter:latest

要运行此容器,请运行以下命令:

docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true VALIDATE_PYTHON_BLACK=true -v /project/directory:/

请注意这里的几件事:

• 我们使用RUN_LOCAL标志运行它以绕过一些 GitHub 操作检查。这会自动将VALIDATE_ALL_CODEBASE设置为 true。

• 我们将本地代码库映射到/tmp/lint以便 linter 可以获取代码。

• 我们设置环境变量的方式当然不一样,但是运行GitHub Super Linter的整体流程还是一样的。

如何在其他 CI 平台上运行 Super Linter

在其他 CI 平台上运行 GitHub Super Linter 与在本地运行它非常相似。这是Tao Yang在 Azure Pipelines 中运行的示例。

- job: lint_tests
  displayName: Lint Tests
  pool:
    vmImage: ubuntu-latest
  steps:
  - script: |
      docker pull github/super-linter:latest
      docker run -e RUN_LOCAL=true -v $(System.DefaultWorkingDirectory):/tmp/lint github/super-linter
    displayName: 'Code Scan using GitHub Super-Linter'

这只是运行我们在本地以脚本形式运行 Super Linter 的命令。您可以在其他 CI 平台上以完全相同的方式运行它。

结论

谢谢你一直陪我到最后。我希望您对 linting 和使用 GitHub Super Linter 有所了解。它肯定是我最喜欢的开源项目之一。

如果您学到了新知识或喜欢阅读本文,请分享它,以便其他人可以看到。在那之前,我们下一篇文章见!

你也可以在 Twitter@rishit_dagli上找到我,我在推特上发布了关于开源和机器学习的信息。