superlint/docs/run-linter-locally.md

112 lines
4.1 KiB
Markdown
Raw Normal View History

2020-01-09 10:48:46 -05:00
# Run Super-Linter locally to test your branch of code
2020-07-21 13:08:05 -04:00
2020-01-09 10:48:46 -05:00
If you want to test locally against the **Super-Linter** to test your branch of code, you will need to complete the following:
2020-07-21 13:08:05 -04:00
2020-01-09 10:48:46 -05:00
- Clone your testing source code to your local environment
- Install Docker to your local environment
- Pull the container down
- Run the container
- Debug/Troubleshoot
## Install Docker to your local machine
2020-07-21 13:08:05 -04:00
2020-01-09 10:48:46 -05:00
You can follow the link below on how to install and configure **Docker** on your local machine
2020-07-21 13:08:05 -04:00
2020-01-09 10:48:46 -05:00
- [Docker Install Documentation](https://docs.docker.com/install/)
## Download the latest Super-Linter Docker container
2020-07-21 13:08:05 -04:00
2020-01-09 10:48:46 -05:00
- Pull the latest **Docker** container down from **DockerHub**
- `docker pull ghcr.io/super-linter/super-linter:latest`
2020-07-21 13:08:05 -04:00
Once the container has been downloaded to your local environment, you can then begin the process, or running the container against your codebase.
2020-01-09 10:48:46 -05:00
## Run the container Locally
2020-07-21 13:08:05 -04:00
2020-01-09 10:48:46 -05:00
- You can run the container locally with the following **Base** flags to run your code:
- `docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true -v /path/to/local/codebase:/tmp/lint super-linter/super-linter`
- 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`
2020-01-09 11:33:07 -05:00
- **NOTE:** You need to pass the `RUN_LOCAL` flag to bypass some of the GitHub Actions checks, as well as the mapping of your local codebase to `/tmp/lint` so that the linter can pick up the code
2020-06-19 05:52:14 -04:00
- **NOTE:** 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.
2020-01-09 11:33:07 -05:00
- **NOTE:** The flag:`RUN_LOCAL` will set: `VALIDATE_ALL_CODEBASE` to true. This means it will scan **all** the files in the directory you have mapped. If you want to only validate a subset of your codebase, map a folder with only the files you wish to have linted
- **NOTE:** Add the `--rm` docker flag to automatically remove the container after execution.
2020-05-14 10:24:23 -04:00
### Flags for running Locally
2020-07-21 13:08:05 -04:00
You can add as many **Additional** flags as needed, documented in [README.md](../README.md#Environment-variables)
2020-01-09 10:48:46 -05:00
## Sharing Environment variables between Local and CI
If you run both locally and on CI it's very helpful to only have to define your env variables once. This is one setup using Github's [STRTA](https://github.com/github/scripts-to-rule-them-all) style to do so.
### .github/super-linter.env
This is the shared location for the super-linter variables. Example:
```bash
VALIDATE_ALL_CODEBASE=true
VALIDATE_DOCKERFILE_HADOLINT=false
VALIDATE_EDITORCONFIG=false
VALIDATE_GITLEAKS=false
```
### scripts/lint
This always runs the local docker based linting.
```bash
docker run --rm \
-e RUN_LOCAL=true \
--env-file ".github/super-linter.env" \
-v "$PWD":/tmp/lint ghcr.io/super-linter/super-linter:v5
```
### scripts/test
This runs the local lint when not on CI.
```bash
if [ "$(whoami)" == "runner" ]; then
echo "We are on GitHub, so don't run lint manually"
else
echo "Running locally because we don't think we are on GitHub"
lint_ci
fi
```
### .github/workflows/ci.yml
This loads the environment variables before running the GitHub Actions job.
```yaml
name: CI
on:
pull_request:
jobs:
lint:
# Run GH Super-Linter against code base
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: cat .github/super-linter.env >> "$GITHUB_ENV"
- name: Lint Code Base
uses: super-linter/super-linter@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DEFAULT_BRANCH: develop
```
2020-01-09 10:48:46 -05:00
## Troubleshooting
### Run container and gain access to the command-line
2020-07-21 13:08:05 -04:00
If you need to run the container locally and gain access to its command-line, you can run the following command:
2020-07-21 13:08:05 -04:00
- `docker run -it --entrypoint /bin/bash ghcr.io/super-linter/super-linter`
- This will drop you in the command-line of the docker container for any testing or troubleshooting that may be needed.
2020-01-09 10:48:46 -05:00
### Found issues
2020-07-21 13:08:05 -04:00
If you find a _bug_ or _issue_, please open a **GitHub** issue at: [super-linter/super-linter/issues](https://github.com/super-linter/super-linter/issues)