Skip to content

linter.md

Latest commit

 

History

History
248 lines (185 loc) · 14.7 KB

linter.md

File metadata and controls

248 lines (185 loc) · 14.7 KB
Raw

GitHub Reusable Workflow: Linter

Linter

Release License Stars PRs Welcome GitHub Verified Creator

Overview

Reusable workflow that performs linting on the codebase. Executes:

Commitlint is disabled by default for scheduled and manual runs, and for pushes with no commits (such as creating a tag on an existing commit). Explicit linter-env validator settings take precedence.

Permissions

  • actions: read
  • contents: read
  • issues: write
  • packages: read
  • pull-requests: write
  • security-events: write
  • statuses: write

Shared linting image

Super-Linter runs in the Hoverkraft image. The image owns toolchain selection, Kubernetes schema defaults, and fallback commitlint rules. Use the same image release for local linting to share these defaults and the bundled linter versions.

The local Dockerfile and workflow pin the same image release and SHA256 digest. Update both references together when updating the image: Dependabot updates Dockerfiles but does not update docker:// workflow references.

Values in linter-env override the toolchain inputs and image defaults. An empty VALIDATE_JAVASCRIPT_TOOLCHAIN or VALIDATE_PYTHON_TOOLCHAIN value disables the corresponding automatic toolchain exclusions. VALIDATE_GIT_COMMITLINT=false disables commitlint. With toolchain selectors enabled, explicit true keeps it enabled without restricting the other validators. Set both selectors to empty strings to use Super-Linter's native VALIDATE_*=true allowlist, including commitlint. Do not mix true and false validator flags in that mode.

CI uses Git change detection according to lint-all and publishes GitHub summaries. Scheduled (schedule) and manual (workflow_dispatch) runs disable commitlint by default because these events do not provide a commit range. Explicit linter-env validator settings take precedence. Local runs use filesystem discovery by default. The workflow also installs project dependencies when package.json declares Prettier plugins; install those dependencies before running the image locally.

GitHub Actions Pinning

Tips: To ensure that all GitHub Actions used in your workflows are pinned to a specific version, you can use the Ratchet tool integrated into this workflow.

docker run -it --rm -v "${PWD}:${PWD}" -w "${PWD}" -u $(id -u):$(id -g) \
  --env GITHUB_TOKEN=$(gh auth token) \
  ghcr.io/sethvargo/ratchet:latest \
  lint ".github/workflows/file-to-lint.yml"

Usage

name: Linter
on:
  push:
    branches:
      - main
permissions: {}
jobs:
  linter:
    uses: hoverkraft-tech/ci-github-common/.github/workflows/linter.yml@4a6ed33ba735d57ebbcd89fe8ed35134de599a67 # 0.39.2
    permissions:
      actions: read
      contents: read
      issues: write
      packages: read
      pull-requests: write
      security-events: write
      statuses: write
    secrets:
      # Token for marking the status of linter run in the Checks section.
      # See https://github.com/super-linter/super-linter#how-to-use.
      # Default GITHUB_TOKEN.
      github-token: ""
    with:
      # JSON array of runner(s) to use.
      # See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
      #
      # Default: `["ubuntu-latest"]`
      runs-on: '["ubuntu-latest"]'

      # Environment variables in multilines format "key=value" to pass to the linter.
      # See https://github.com/super-linter/super-linter.
      linter-env: ""

      # Lint toolchain to use for Super-Linter JavaScript and frontend validators.
      # Supported values: biome, eslint-prettier.
      #
      # Default: `biome`
      javascript-linter-toolchain: biome

      # Lint toolchain to use for Super-Linter Python format validators.
      # Supported values: black, ruff-format.
      #
      # Default: `ruff-format`
      python-linter-toolchain: ruff-format

      # JSON array of languages to analyze with CodeQL.
      # See https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/.
      # Leave empty to disable the check.
      #
      # Default: `["actions"]`
      codeql-languages: '["actions"]'

      # List of files or directories where GitHub Actions and workflows are located.
      # Supports glob patterns.
      # Leave empty to disable the check.
      #
      # Default: `./action.yml
      # ./.github/workflows/**/*.yml
      # ./actions/**/*.yml
      # `
      action-files: |
        ./action.yml
        ./.github/workflows/**/*.yml
        ./actions/**/*.yml

      # Run checks on all files, not just the changed ones.
      # Default: `${{ github.event_name != 'pull_request' }}`
      lint-all: false

Inputs

Workflow Call Inputs

Input Description Required Type Default
runs-on JSON array of runner(s) to use. false string ["ubuntu-latest"]
See https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job.
linter-env Environment variables in multilines format "key=value" to pass to the linter. false string -
See https://github.com/super-linter/super-linter.
javascript-linter-toolchain Lint toolchain to use for Super-Linter JavaScript and frontend validators. false string biome
Supported values: biome, eslint-prettier.
python-linter-toolchain Lint toolchain to use for Super-Linter Python format validators. false string ruff-format
Supported values: black, ruff-format.
codeql-languages JSON array of languages to analyze with CodeQL. false string ["actions"]
See https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/.
Leave empty to disable the check.
action-files List of files or directories where GitHub Actions and workflows are located. false string 
./action.yml
./.github/workflows/**/*.yml
./actions/**/*.yml
Supports glob patterns.
Leave empty to disable the check.
lint-all Run checks on all files, not just the changed ones. false boolean ${{ github.event_name != 'pull_request' }}

Secrets

Secret Description Required
github-token Token for marking the status of linter run in the Checks section. false
See https://github.com/super-linter/super-linter#how-to-use.
Default GITHUB_TOKEN.

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

License

This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2026 hoverkraft-tech

For more details, see the license.

This documentation was automatically generated by CI Dokumentor.