superlint/docs/run-linter-locally.md

163 lines
5.3 KiB
Markdown
Raw Permalink Normal View History

# Run super-linter outside GitHub Actions
2020-07-21 13:08:05 -04:00
If you want to run super-linter outside GitHub Actions, you need a container
runtime engine to run the super-linter container image.
2020-07-21 13:08:05 -04:00
## Run super-linter Locally
You can run the container locally with the following configuration options to
run your code:
```bash
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**.
2020-05-14 10:24:23 -04:00
Notes:
2020-07-21 13:08:05 -04:00
- 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.
- You can add as many configuration options as needed. Configuration options are
documented in the [readme](../README.md#configure-super-linter).
2020-01-09 10:48:46 -05:00
### GitLab
To run Super-linter in your GitLab CI/CD pipeline, You can use the following
snippet:
```yaml
super-linter:
# More info at https://github.com/super-linter/super-linter
stage: Super-linter
# Use a specific Super-linter version instead of latest for more reproducible builds
image: super-linter/super-linter:latest
2024-08-15 04:21:26 -04:00
script: ["true"]
variables:
RUN_LOCAL: "true"
DEFAULT_WORKSPACE: $CI_PROJECT_DIR
```
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](https://code.visualstudio.com/docs/remote/containers).
## 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:
1. Create a configuration file for super-linter `super-linter.env`. For example:
2024-08-15 04:21:26 -04:00
```bash
VALIDATE_ALL_CODEBASE=true
```
1. Load the super-linter configuration file when running outside GitHub Actions:
2024-08-15 04:21:26 -04:00
```bash
docker run --rm \
-e RUN_LOCAL=true \
--env-file ".github/super-linter.env" \
-v "$(pwd)":/tmp/lint \
ghcr.io/super-linter/super-linter:latest
```
1. Load the super-linter configuration file when running in GitHub Actions by
2024-08-15 04:21:26 -04:00
adding the following step to the GitHub Actions workflow that runs
super-linter, after checking out your repository and before running
super-linter:
2024-08-15 04:21:26 -04:00
```yaml
- 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"
2024-08-15 04:21:26 -04:00
```
## 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:
1. [Create a fine-grained GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
2024-08-15 04:21:26 -04:00
The token only needs to have public/read-only access.
1. Store the generated personal access token in a file in the top-level
2024-08-15 04:21:26 -04:00
directory (This file is ignored by Git).
2024-08-15 04:21:26 -04:00
```bash
echo "github_pat_XXXXXX_XXXXXX" > .github-personal-access-token
```
1. Run the build process:
2024-08-15 04:21:26 -04:00
```bash
. ./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`:
```bash
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.
```shell
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
2020-01-09 10:48:46 -05:00
To get the list of the available `Make` targets, run the following command:
2020-07-21 13:08:05 -04:00
```shell
make help
```
### Automatically fix formatting and linting issues
To automatically fix linting and formatting issues when supported, run the
following command:
```shell
make fix-codebase
```