Merge pull request #39 from github/addLocal

Adding Functionality

.github/run-linter-locally.md

@@ -0,0 +1,81 @@
+# 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
+  - **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
+- You can add as many **Additional** flags as needed:
+  - **VALIDATE_YAML**
+    - `-e VALIDATE_YAML=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_JSON**
+    - `-e VALIDATE_JSON=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_XML**
+    - `-e VALIDATE_XML=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_MD**
+    - `-e VALIDATE_MD=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_BASH**
+    - `-e VALIDATE_BASH=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_PERL**
+    - `-e VALIDATE_PERL=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_PYTHON**
+    - `-e VALIDATE_PYTHON=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_RUBY**
+    - `-e VALIDATE_RUBY=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_COFFEE**
+    - `-e VALIDATE_COFFEE=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_ANSIBLE**
+    - `-e VALIDATE_ANSIBLE=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_JAVASCRIPT**
+    - `-e VALIDATE_JAVASCRIPT=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **ANSIBLE_DIRECTORY**
+    - `-e ANSIBLE_DIRECTORY=</path/local/to/codebase/with/ansible>`
+    - 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`

Dockerfile

@@ -90,7 +90,8 @@ ENV GITHUB_SHA=${GITHUB_SHA} \
     VALIDATE_COFFEE=${VALIDATE_COFFEE} \
     VALIDATE_ANSIBLE=${VALIDATE_ANSIBLE} \
     VALIDATE_JAVASCRIPT=${VALIDATE_JAVASCRIPT} \
-    ANSIBLE_DIRECTORY=${ANSIBLE_DIRECTORY}
+    ANSIBLE_DIRECTORY=${ANSIBLE_DIRECTORY} \
+    RUN_LOCAL=${RUN_LOCAL}
 
 #############################
 # Copy scripts to container #

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)

lib/linter.sh

@@ -56,13 +56,16 @@ VALIDATE_RUBY="${VALIDATE_RUBY}"                  # Boolean to validate language
 VALIDATE_COFFEE="${VALIDATE_COFFEE}"              # Boolean to validate language
 VALIDATE_ANSIBLE="${VALIDATE_ANSIBLE}"            # Boolean to validate language
 VALIDATE_JAVASCRIPT="${VALIDATE_JAVASCRIPT}"      # Boolean to validate language
+RUN_LOCAL="${RUN_LOCAL}"                          # Boolean to see if we are running locally
 
 ################
 # Default Vars #
 ################
 DEFAULT_VALIDATE_ALL_CODEBASE='true'                  # Default value for validate all files
 DEFAULT_VALIDATE_LANGUAGE='true'                      # Default to validate language
+DEFAULT_WORKSPACE='/tmp/lint'                         # Default workspace if running locally
 DEFAULT_ANSIBLE_DIRECTORY="$GITHUB_WORKSPACE/ansible" # Default Ansible Directory
+DEFAULT_RUN_LOCAL='false'                             # default value for debugging
 RAW_FILE_ARRAY=()                                     # Array of all files that were changed
 
 ##########################
@@ -1900,75 +1903,116 @@ GetGitHubVars()
   echo "--------------------------------------------"
   echo "Gathering GitHub information..."
 
-  ############################
+  ##########################
-  # Validate we have a value #
+  # Get the run local flag #
-  ############################
+  ##########################
-  if [ -z "$GITHUB_SHA" ]; then
+  if [ -z "$RUN_LOCAL" ]; then
-    echo "ERROR! Failed to get [GITHUB_SHA]!"
+    ##################################
-    echo "ERROR:[$GITHUB_SHA]"
+    # No flag passed, set to default #
-    exit 1
+    ##################################
-  else
+    RUN_LOCAL="$DEFAULT_RUN_LOCAL"
-    echo "Successfully found:[GITHUB_SHA], value:[$GITHUB_SHA]"
   fi
 
-  ############################
+  ###############################
-  # Validate we have a value #
+  # Convert string to lowercase #
-  ############################
+  ###############################
-  if [ -z "$GITHUB_WORKSPACE" ]; then
+  RUN_LOCAL=$(echo "$RUN_LOCAL" | awk '{print tolower($0)}')
-    echo "ERROR! Failed to get [GITHUB_WORKSPACE]!"
+  #################################
-    echo "ERROR:[$GITHUB_WORKSPACE]"
+  # Check if were running locally #
-    exit 1
+  #################################
+  if [[ "$RUN_LOCAL" != "false" ]]; then
+    ##########################################
+    # We are running locally for a debug run #
+    ##########################################
+    echo "NOTE: ENV VAR [RUN_LOCAL] has been set to:[true]"
+    echo "bypassing GitHub Actions variables..."
+    echo "Linting all files in mapped directory:[$DEFAULT_WORKSPACE]"
+
+    # No need to touch or set the GITHUB_SHA
+    # No need to touch or set the GITHUB_EVENT_PATH
+    # No need to touch or set the GITHUB_ORG
+    # No need to touch or set the GITHUB_REPO
+
+    ############################
+    # Set the GITHUB_WORKSPACE #
+    ############################
+    GITHUB_WORKSPACE="$DEFAULT_WORKSPACE"
+
+    #################################
+    # Set the VALIDATE_ALL_CODEBASE #
+    #################################
+    VALIDATE_ALL_CODEBASE="$DEFAULT_VALIDATE_ALL_CODEBASE"
   else
-    echo "Successfully found:[GITHUB_WORKSPACE], value:[$GITHUB_WORKSPACE]"
+    ############################
-  fi
+    # Validate we have a value #
+    ############################
+    if [ -z "$GITHUB_SHA" ]; then
+      echo "ERROR! Failed to get [GITHUB_SHA]!"
+      echo "ERROR:[$GITHUB_SHA]"
+      exit 1
+    else
+      echo "Successfully found:[GITHUB_SHA], value:[$GITHUB_SHA]"
+    fi
 
-  ############################
+    ############################
-  # Validate we have a value #
+    # Validate we have a value #
-  ############################
+    ############################
-  if [ -z "$GITHUB_EVENT_PATH" ]; then
+    if [ -z "$GITHUB_WORKSPACE" ]; then
-    echo "ERROR! Failed to get [GITHUB_EVENT_PATH]!"
+      echo "ERROR! Failed to get [GITHUB_WORKSPACE]!"
-    echo "ERROR:[$GITHUB_EVENT_PATH]"
+      echo "ERROR:[$GITHUB_WORKSPACE]"
-    exit 1
+      exit 1
-  else
+    else
-    echo "Successfully found:[GITHUB_EVENT_PATH], value:[$GITHUB_EVENT_PATH]"
+      echo "Successfully found:[GITHUB_WORKSPACE], value:[$GITHUB_WORKSPACE]"
-  fi
+    fi
 
-  ##################################################
+    ############################
-  # Need to pull the GitHub Vars from the env file #
+    # Validate we have a value #
-  ##################################################
+    ############################
+    if [ -z "$GITHUB_EVENT_PATH" ]; then
+      echo "ERROR! Failed to get [GITHUB_EVENT_PATH]!"
+      echo "ERROR:[$GITHUB_EVENT_PATH]"
+      exit 1
+    else
+      echo "Successfully found:[GITHUB_EVENT_PATH], value:[$GITHUB_EVENT_PATH]"
+    fi
 
-  ######################
+    ##################################################
-  # Get the GitHub Org #
+    # Need to pull the GitHub Vars from the env file #
-  ######################
+    ##################################################
-  # shellcheck disable=SC2002
-  GITHUB_ORG=$(cat "$GITHUB_EVENT_PATH" | jq -r '.repository.owner.login' )
 
-  ############################
+    ######################
-  # Validate we have a value #
+    # Get the GitHub Org #
-  ############################
+    ######################
-  if [ -z "$GITHUB_ORG" ]; then
+    # shellcheck disable=SC2002
-    echo "ERROR! Failed to get [GITHUB_ORG]!"
+    GITHUB_ORG=$(cat "$GITHUB_EVENT_PATH" | jq -r '.repository.owner.login' )
-    echo "ERROR:[$GITHUB_ORG]"
-    exit 1
-  else
-    echo "Successfully found:[GITHUB_ORG], value:[$GITHUB_ORG]"
-  fi
 
-  #######################
+    ############################
-  # Get the GitHub Repo #
+    # Validate we have a value #
-  #######################
+    ############################
-  # shellcheck disable=SC2002
+    if [ -z "$GITHUB_ORG" ]; then
-  GITHUB_REPO=$(cat "$GITHUB_EVENT_PATH"| jq -r '.repository.name' )
+      echo "ERROR! Failed to get [GITHUB_ORG]!"
+      echo "ERROR:[$GITHUB_ORG]"
+      exit 1
+    else
+      echo "Successfully found:[GITHUB_ORG], value:[$GITHUB_ORG]"
+    fi
 
-  ############################
+    #######################
-  # Validate we have a value #
+    # Get the GitHub Repo #
-  ############################
+    #######################
-  if [ -z "$GITHUB_REPO" ]; then
+    # shellcheck disable=SC2002
-    echo "ERROR! Failed to get [GITHUB_REPO]!"
+    GITHUB_REPO=$(cat "$GITHUB_EVENT_PATH"| jq -r '.repository.name' )
-    echo "ERROR:[$GITHUB_REPO]"
+
-    exit 1
+    ############################
-  else
+    # Validate we have a value #
-    echo "Successfully found:[GITHUB_REPO], value:[$GITHUB_REPO]"
+    ############################
+    if [ -z "$GITHUB_REPO" ]; then
+      echo "ERROR! Failed to get [GITHUB_REPO]!"
+      echo "ERROR:[$GITHUB_REPO]"
+      exit 1
+    else
+      echo "Successfully found:[GITHUB_REPO], value:[$GITHUB_REPO]"
+    fi
   fi
 
   ############################################
@@ -1978,20 +2022,25 @@ GetGitHubVars()
   echo "--------------------------------------------"
   echo "Gathering User provided information..."
 
-  ###############################
+  ###########################################
-  # Convert string to lowercase #
+  # Skip validation if were running locally #
-  ###############################
+  ###########################################
-  VALIDATE_ALL_CODEBASE=$(echo "$VALIDATE_ALL_CODEBASE" | awk '{print tolower($0)}')
+  if [[ "$RUN_LOCAL" != "true" ]]; then
-  ######################################
+    ###############################
-  # Validate we should check all files #
+    # Convert string to lowercase #
-  ######################################
+    ###############################
-  if [[ "$VALIDATE_ALL_CODEBASE" != "false" ]]; then
+    VALIDATE_ALL_CODEBASE=$(echo "$VALIDATE_ALL_CODEBASE" | awk '{print tolower($0)}')
-    # Set to true
+    ######################################
-    VALIDATE_ALL_CODEBASE="$DEFAULT_VALIDATE_ALL_CODEBASE"
+    # Validate we should check all files #
-    echo "- Validating ALL files in code base..."
+    ######################################
-  else
+    if [[ "$VALIDATE_ALL_CODEBASE" != "false" ]]; then
-    # Its false
+      # Set to true
-    echo "- Only validating [new], or [edited] files in code base..."
+      VALIDATE_ALL_CODEBASE="$DEFAULT_VALIDATE_ALL_CODEBASE"
+      echo "- Validating ALL files in code base..."
+    else
+      # Its false
+      echo "- Only validating [new], or [edited] files in code base..."
+    fi
   fi
 
   ###############################