From 601eb398127a807f08fc39d9a1f79a5a4be140bd Mon Sep 17 00:00:00 2001 From: Lucas Gravley <29484535+admiralAwkbar@users.noreply.github.com> Date: Thu, 9 Jan 2020 09:48:46 -0600 Subject: [PATCH] adding docs --- .github/run-linter-locally.md | 85 +++++++++++++++++++++++++++++++++++ README.md | 12 +++-- 2 files changed, 90 insertions(+), 7 deletions(-) create mode 100644 .github/run-linter-locally.md diff --git a/.github/run-linter-locally.md b/.github/run-linter-locally.md new file mode 100644 index 00000000..a2daa098 --- /dev/null +++ b/.github/run-linter-locally.md @@ -0,0 +1,85 @@ +# Run Super-Linter locally to test your branch of code +If you want to test locally against the **Super-Linter** to test your branch of code, you will need to complete the following: +- 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 +You can follow the link below on how to install and configure **Docker** on your local machine +- [Docker Install Documentation](https://docs.docker.com/install/) + +## Download the latest Super-Linter Docker container +- Pull the latest **Docker** container down from **DockerHub** + - `docker pull admiralawkbar/super-linter:latest` +Once the container has been downloaded to your local environment, you can then begin the process, or running the container against your codebase. + +## Run the container Locally +- You can run the container locally with the following **Base** flags to run your code: + - `docker run -e RUN_LOCAL=true -v /path/to/local/codebase:/tmp/lint admiralawkbar/super-linter` + - **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 +- You can add as many **Additional** flags as needed: + - **VALIDATE_ALL_CODEBASE** + - `-e VALIDATE_ALL_CODEBASE=` + - Default: `true` + - Will parse the entire repository and find all files to validate across all types + - **NOTE:** When set to `false`, only **new** or **edited** files will be parsed for validation + - **VALIDATE_YAML** + - `-e VALIDATE_YAML=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_JSON** + - `-e VALIDATE_JSON=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_XML** + - `-e VALIDATE_XML=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_MD** + - `-e VALIDATE_MD=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_BASH** + - `-e VALIDATE_BASH=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_PERL** + - `-e VALIDATE_PERL=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_PYTHON** + - `-e VALIDATE_PYTHON=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_RUBY** + - `-e VALIDATE_RUBY=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_COFFEE** + - `-e VALIDATE_COFFEE=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_ANSIBLE** + - `-e VALIDATE_ANSIBLE=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **VALIDATE_JAVASCRIPT** + - `-e VALIDATE_JAVASCRIPT=` + - Default: `true` + - Flag to enable or disable the linting process of the language + - **ANSIBLE_DIRECTORY** + - `-e ANSIBLE_DIRECTORY=` + - Default: `/ansible` + - Flag to set the root directory for Ansible file location(s) + +## Troubleshooting + +### Run container and gain access to the command line +If you need to run the container locally and gain access to its command line, you can run the following command: +- `docker run -it --entrypoint /bin/bash admiralawkbar/super-linter` +- This will drop you in the command line of the docker container for any testing or troubleshooting that may be needed. + +### Found issues +If you find a *bug* or *issue*, please open a **GitHub** issue at: `https://github.com/github/super-linter/issues` diff --git a/README.md b/README.md index 1566a3f3..2b480d0c 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ # Super-Linter - This repository is for the **GitHub** Action to run a **Super-Linter**. Developers on **GitHub** can call this Action to lint their code base with the following list of linters: - - **Ruby** (Rubocop) - **Shell** (Shellcheck) - **Ansible** (Ansible-lint) @@ -17,7 +15,6 @@ Developers on **GitHub** can call this Action to lint their code base with the f - **Javascript** (eslint)(standard) ## How to use - To use this **GitHub** Action you will need to complete the following: - Copy **any** or **all** template rules files from `TEMPLATES/` into your repository in the location: `.github/linters/` - If your repository does not have rules files, they will fall back to defaults in this repositories `TEMPLATE` folder @@ -25,7 +22,6 @@ To use this **GitHub** Action you will need to complete the following: - Enjoy your more stable, and cleaner code base ### Example connecting GitHub Action Workflow - In your repository you should have a `workflows` folder with **GitHub** Action similar to below: - `.github/workflows/linter.yml` @@ -81,6 +77,7 @@ jobs: VALIDATE_ANSIBLE: false ... ``` + ## Env Vars The super-linter allows you to pass the following `ENV` variables to be able to trigger different functionality: - **VALIDATE_ALL_CODEBASE** @@ -123,16 +120,17 @@ The super-linter allows you to pass the following `ENV` variables to be able to - **ANSIBLE_DIRECTORY** - Default: `/ansible` - Flag to set the root directory for Ansible file location(s) -## Docker Hub +## Docker Hub The **Docker** container that is built from this repository is located at `https://cloud.docker.com/u/admiralawkbar/repository/docker/admiralawkbar/super-linter` -## How to contribute +## Running Super-Linter locally (troubleshooting/debugging/enhancements) +If you find that you need to run super-linter locally, you can follow the documentation at [Running super-linter locally](https://github.com/github/super-linter/blob/master/.github/run-linter-locally.md) +## How to contribute If you would like to help contribute to this **Github** Action, please see [CONTRIBUTING](https://github.com/github/super-linter/blob/master/.github/CONTRIBUTING.md) -------------------------------------------------------------------------------- ### License - - [License](https://github.com/github/super-linter/blob/master/LICENSE)