Run super-linter outside GitHub Actions

If you want to run super-linter outside GitHub Actions, you need a container runtime engine to run the super-linter container image.

Run super-linter Locally

You can run the container locally with the following configuration options to run your code:

docker run \
  -e LOG_LEVEL=DEBUG \
  -e RUN_LOCAL=true \
  -v /path/to/local/codebase:/tmp/lint \
  --rm \
  ghcr.io/super-linter/super-linter:latest

This example uses the latest container image version. If you're trying to reproduce an issue, or running super-linter as part of your CI pipeline, we recommend that you refer to a specific version instead.

Notes:

To run against a single file you can use: docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true -v /path/to/local/codebase/file:/tmp/lint/file ghcr.io/super-linter/super-linter
You need to pass the RUN_LOCAL option to bypass some of the GitHub Actions checks, as well as the mapping of your local codebase to /tmp/lint.
If you want to override the /tmp/lint folder, you can set the DEFAULT_WORKSPACE environment variable to point to the folder you'd prefer to scan.
If the default branch for your repository doesn't match the default, you can use the DEFAULT_BRANCH variable to set the default branch. For more information about the default value of the DEFAULT_BRANCH variable, see the Readme.
You can add as many configuration options as needed. Configuration options are documented in the readme.

Working with Git Worktrees

Git worktrees allow you to have multiple working directories associated with a single Git repository, which is useful for working on different branches simultaneously without switching contexts.

When running super-linter in a Git worktree, you must mount both the worktree directory and the main Git repository directory into the container. This is because worktrees store only the working files, while Git metadata remains in the main repository's .git directory.

Example Docker Command for Git Worktrees

docker run \
  -e LOG_LEVEL=DEBUG \
  -e RUN_LOCAL=true \
  -v /path/to/your/worktree:/tmp/lint \
  -v /path/to/main/repo/.git:/path/to/main/repo/.git \
  --rm \
  ghcr.io/super-linter/super-linter:latest

Finding Your Git Common Directory

To find the main Git directory that needs to be mounted, use the following Git command from within your worktree:

git rev-parse --path-format=absolute --git-common-dir

This will output the absolute path to the main Git directory, for example:

/path/to/main/repo/.git

Use this output as the source path for your Docker volume mount.

Helpful Error Messages

If you forget to mount the main Git directory, super-linter will detect this and provide a helpful error message indicating exactly which directory needs to be mounted:

/path/to/main/repo/.git/worktrees/my-worktree doesn't exist.
Ensure to mount it as a volume when running the Super-linter container.
See https://github.com/super-linter/super-linter/blob/main/docs/run-linter-locally.md

GitLab

To run Super-linter in your GitLab CI/CD pipeline, You can use the following snippet:

super-linter:
  stage: lint
  image:
    name: ghcr.io/super-linter/super-linter:latest # set a stable version tag and the sha checksum in production for reproducible runs
    entrypoint: [""]
  script:
    - git fetch origin $CI_DEFAULT_BRANCH # clone the default branch from this repository
    - /action/lib/linter.sh
  variables:
    # More info at https://github.com/super-linter/super-linter?tab=readme-ov-file#configure-super-linter
    GIT_DEPTH: 0 # clone the whole history of the required branches
    RUN_LOCAL: "true"
    DEFAULT_WORKSPACE: $CI_PROJECT_DIR
    DEFAULT_BRANCH: $CI_DEFAULT_BRANCH

Note that this is a high-level example that you should customize for your needs.

Run on Codespaces and Visual Studio Code

This repository provides a DevContainer for remote development.

Share Environment variables between environments

To avoid duplication if you run super-linter both locally and in other environements, such as CI, you can define configuration options once, and load them accordingly:

Create a configuration file for super-linter super-linter.env. For example:
```
VALIDATE_ALL_CODEBASE=true
```

Load the super-linter configuration file when running outside GitHub Actions:

docker run --rm \
    -e RUN_LOCAL=true \
    --env-file ".github/super-linter.env" \
    -v "$(pwd)":/tmp/lint \
    ghcr.io/super-linter/super-linter:latest

Load the super-linter configuration file when running in GitHub Actions by adding the following step to the GitHub Actions workflow that runs super-linter, after checking out your repository and before running super-linter:

- name: Load super-linter configuration
  # Use grep inverse matching to exclude eventual comments in the .env file
  # because the GitHub Actions command to set environment variables doesn't
  # support comments.
  # Ref: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable
  run: grep -v '^#' .github/super-linter.env >> "$GITHUB_ENV"

Build the container image and run the test suite locally

To run the build and test process locally, in the top-level super-linter directory, do the following:

Create a fine-grained GitHub personal access token. The token only needs to have public/read-only access.
Store the generated personal access token in a file in the top-level directory (This file is ignored by Git).
```
echo "github_pat_XXXXXX_XXXXXX" > .github-personal-access-token
```
Run the build process:
```
. ./scripts/build-metadata.sh && make
```

To avoid invalidating the build cache because of changing values of build arguments, you can set build arguments to arbitrary values before running make, instead of sourcing scripts/build-metadata.sh:

BUILD_DATE=2023-12-12T09:32:05Z \
BUILD_REVISION=83c16f63caa9d432df4519efb4c58a56e2190bd6 \
BUILD_VERSION=83c16f63caa9d432df4519efb4c58a56e2190bd6 \
make

Run the test suite against an arbitrary super-linter container image

You can run the test suite against an arbitrary super-linter container image.

Here is an example that runs the test suite against the v5.4.3 container image version.

CONTAINER_IMAGE_ID="ghcr.io/super-linter/super-linter:v5.4.3" \
BUILD_DATE="2023-10-17T17:00:53Z" \
BUILD_REVISION=b0d1acee1f8050d1684a28ddbf8315f81d084fe9 \
BUILD_VERSION=b0d1acee1f8050d1684a28ddbf8315f81d084fe9 \
make docker-pull test

Initialize the BUILD_DATE, BUILD_REVISION, and BUILD_VERSION variables with the values for that specific container image version. You can get these values from the build log for that version.

Get the list of available build targets

To get the list of the available Make targets, run the following command:

make help

Automatically fix formatting and linting issues

To automatically fix linting and formatting issues when supported, run the following command:

make fix-codebase

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!