actions/superlint
1
0
Fork 0
mirror of https://github.com/super-linter/super-linter.git synced 2024-12-24 00:02:16 -05:00
Code Issues Projects Releases Packages Wiki Activity

Update documentation (#4981)

Browse source 
* Update documentation

* Fix typos

* Update security policy

* Remove outdated instructions

* Fix list

* Add more info to config load step

* Don't test linter.yml

* Point to the cd workflow in README

* Move badge up

* Add info about Make help

---------

Co-authored-by: Zack Koppert <zkoppert@github.com>
This commit is contained in:
Marco Ferrari 2023-12-11 22:35:20 +01:00 committed by GitHub
parent 037997ac19
commit d465382ed5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 211 additions and 569 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
.github/CONTRIBUTING.md vendored
View file

@ -1,67 +1,28 @@
# Contributing
:wave: Hi there!
We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
We're thrilled that you'd like to contribute to this project.
Your help is essential for keeping it great.
## Submitting a pull request
[Pull Requests][pulls] are used for adding new playbooks, roles, and documents to the repository, or editing the existing ones.
We use [pull requests](https://github.com/super-linter/super-linter/pulls) to
contribute new features, fixes, or documentation.
**With write access**
Here are a few things you can do that will increase the likelihood of your pull
request being accepted:
1. Clone the repository (only if you have write access)
1. Create a new branch: `git checkout -b my-branch-name`
1. Make your change
1. Push and [submit a pull request][pr]
1. Pat yourself on the back and wait for your pull request to be reviewed and merged.
- Keep your change as focused as possible. If there are multiple changes you
would like to make that are not dependent upon each other, submit them as
separate pull requests.
- Write [descriptive commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
**Without write access**
1. [Fork][fork] and clone the repository
1. Create a new branch: `git checkout -b my-branch-name`
1. Make your change
1. Push to your fork and [submit a pull request][pr]
1. Pat your self on the back and wait for your pull request to be reviewed and merged.
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
- Write [good commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
Draft pull requests are also welcome to get feedback early on, or if there is something blocking you.
- Create a branch with a name that identifies the user and nature of the changes (similar to `user/branch-purpose`)
- Open a pull request
### CI/CT/CD
The **Super-Linter** has _CI/CT/CD_ configured utilizing **GitHub** Actions.
- When a branch is created and code is pushed, a **GitHub** Action is triggered for building the new **Docker** container with the new codebase
- The **Docker** container is then ran against the _test cases_ to validate all code sanity
- `.automation/test` contains all test cases for each language that should be validated
- These **GitHub** Actions utilize the Checks API and Protected Branches to help follow the SDLC
- When the Pull Request is merged to main, the **Super-Linter** **Docker** container is then updated and deployed with the new codebase
- **Note:** The branch's **Docker** container is also removed from **DockerHub** to cleanup after itself
## Releasing
If you are the current maintainer of this action you can create releases from the `Release` page of the repository.
- It will notify the issue it has seen the information and starts the Actions job
- It will create a branch and update the `actions.yml` with the new version supplied to the issue
- It will then create a PR with the updated code
- It will then create the build the artifacts needed
- it will then publish the release and merge the PR
- A GitHub Action will Publish the Docker image to GitHub Package Registry once a Release is created
- A GitHub Action will Publish the Docker image to Docker Hub once a Release is created
Draft pull requests are also welcome to get feedback early on, or if there is
something blocking you.
## Resources
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Using Pull Requests](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
- [GitHub Help](https://docs.github.com/en)
[pulls]: https://github.com/super-linter/super-linter/pulls
[pr]: https://github.com/super-linter/super-linter/compare
[fork]: https://github.com/super-linter/super-linter/fork

445
README.md
View file

@ -1,52 +1,25 @@
# Super-Linter
This repository is for the **GitHub Action** to run a **Super-Linter**.
It is a simple combination of various linters, written in `bash`, to help validate your source code.
This repository is for the **GitHub Action** to run a **Super-Linter**, a
ready-to-run collection of linters and code analyzers, to help validate your
source code.
**The end goal of this tool:**
The goal of super-linter is to help you establish best practices and consistent
formatting across multiple programming languages, and ensure developers are
adhering to those conventions.
- Prevent broken code from being uploaded to the default branch (_Usually_ `master` or `main`)
- Help establish coding best practices across multiple languages
- Build guidelines for code layout and format
- Automate the process to help streamline code reviews
Super-linter analyzes source code files using several tools, and reports the
issues that those tools find as console output, and as
[GitHub Actions status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks).
## Table of Contents
Super-linter is licensed under a
[MIT License](https://github.com/super-linter/super-linter/blob/main/LICENSE).
- [Super-Linter](#super-linter)
- [Table of Contents](#table-of-contents)
- [How it Works](#how-it-works)
- [Supported Linters](#supported-linters)
- [How to use](#how-to-use)
- [Example connecting GitHub Action Workflow](#example-connecting-github-action-workflow)
- [Add Super-Linter badge in your repository README](#add-super-linter-badge-in-your-repository-readme)
- [Images](#images)
- [Standard Image](#standard-image)
- [Slim Image](#slim-image)
- [Environment variables](#environment-variables)
- [Template rules files](#template-rules-files)
- [Using your own rules files](#using-your-own-rules-files)
- [Disabling rules](#disabling-rules)
- [Using your own SSH key](#using-your-own-ssh-key)
- [Filter linted files](#filter-linted-files)
- [Run Super-Linter outside GitHub Actions](#run-super-linter-outside-github-actions)
- [Local (troubleshooting/debugging/enhancements)](#local-troubleshootingdebuggingenhancements)
- [Azure](#azure)
- [GitLab](#gitlab)
- [Codespaces and Visual Studio Code](#codespaces-and-visual-studio-code)
- [SSL Certs](#ssl-certs)
- [Limitations](#limitations)
- [How to contribute](#how-to-contribute)
- [License](#license)
[![Super-Linter](https://github.com/super-linter/super-linter/actions/workflows/cd.yml/badge.svg)](https://github.com/marketplace/actions/super-linter)
## How it Works
## Supported linters and code analyzers
The super-linter finds issues and reports them to the console output. Fixes are suggested in the console output but not automatically fixed, and a status check will show up as failed on the pull request.
The design of the **Super-Linter** is currently to allow linting to occur in **GitHub Actions** as a part of continuous integration occurring on pull requests as the commits get pushed. It works best when commits are being pushed early and often to a branch with an open or draft pull request. There is some desire to move this closer to local development for faster feedback on linting errors but this is not yet supported.
## Supported Linters
Developers on **GitHub** can call the **GitHub Action** to lint their codebase with the following list of linters:
Super-linter supports the following tools:
| _Language_ | _Linter_ |
|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@ -101,178 +74,81 @@ Developers on **GitHub** can call the **GitHub Action** to lint their codebase w
| **XML** | [LibXML](http://xmlsoft.org/) |
| **YAML** | [YamlLint](https://github.com/adrienverge/yamllint) |
## How to use
## Get started
More in-depth [tutorial](https://www.youtube.com/watch?v=EDAmFKO4Zt0&t=118s) available
To use this **GitHub** Action you will need to complete the following:
To run super-linter as a GitHub Action, you do the following:
1. Create a new file in your repository called `.github/workflows/linter.yml`
2. Copy the example workflow from below into that new file, no extra configuration required
3. Commit that file to a new branch
4. Open up a pull request and observe the action working
5. Enjoy your more _stable_, and _cleaner_ codebase
6. Check out the [Wiki](https://github.com/super-linter/super-linter/wiki) for customization options
1. Create a new [GitHub Actions workflow](https://docs.github.com/en/actions/using-workflows/about-workflows#about-workflows) in your repository with the following content:
**NOTE:** If you pass the _Environment_ variable `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` in your workflow, then the **GitHub Super-Linter** will mark the status of each individual linter run in the Checks section of a pull request. Without this you will only see the overall status of the full run. There is no need to set the **GitHub** Secret as it is automatically set by GitHub, it only needs to be passed to the action.
```yaml
---
name: Lint
### Example connecting GitHub Action Workflow
on: # yamllint disable-line rule:truthy
push: null
pull_request: null
In your repository you should have a `.github/workflows` folder with **GitHub** Action similar to below:
jobs:
build:
name: Lint
runs-on: ubuntu-latest
- `.github/workflows/linter.yml`
- Example file can be found at [`TEMPLATES/linter.yml`](TEMPLATES/linter.yml)
permissions:
contents: read
packages: read
# To report GitHub Actions status checks
statuses: write
This file should have the following code:
steps:
- name: Checkout code
uses: actions/checkout@v4
```yml
---
#################################
#################################
## Super Linter GitHub Actions ##
#################################
#################################
name: Lint Code Base
- name: Super-linter
uses: super-linter/super-linter@v5
env:
DEFAULT_BRANCH: main
# To report GitHub Actions status checks
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
...
```
#############################
# Start the job on all push #
#############################
on:
push:
branches-ignore: [master, main]
# Remove the line above to run when pushing to master or main
pull_request:
branches: [master, main]
1. Commit that file to a new branch.
1. Push the new commit to the remote repository.
1. Create a new pull request to observe the results.
###############
# Set the Job #
###############
jobs:
build:
# Name the Job
name: Lint Code Base
# Set the agent to run on
runs-on: ubuntu-latest
## Add Super-Linter badge in your repository README
############################################
# Grant status permission for MULTI_STATUS #
############################################
permissions:
contents: read
packages: read
statuses: write
##################
# Load all steps #
##################
steps:
##########################
# Checkout the code base #
##########################
- name: Checkout Code
uses: actions/checkout@v4
with:
# Full git history is needed to get a proper
# list of changed files within `super-linter`
fetch-depth: 0
################################
# Run Linter against code base #
################################
- name: Lint Code Base
uses: super-linter/super-linter@v5
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
### Add Super-Linter badge in your repository README
You can show Super-Linter status with a badge in your repository README
[![GitHub Super-Linter](https://github.com/super-linter/super-linter/actions/workflows/ci.yml/badge.svg)](https://github.com/marketplace/actions/super-linter)
Format:
```markdown
[![GitHub Super-Linter](https://github.com/<OWNER>/<REPOSITORY>/actions/workflows/<WORKFLOW_FILE_NAME>/badge.svg)](https://github.com/marketplace/actions/super-linter)
```
You can show Super-Linter status with a badge in your repository README:
Example:
```markdown
[![GitHub Super-Linter](https://github.com/super-linter/super-linter/actions/workflows/ci.yml/badge.svg)](https://github.com/marketplace/actions/super-linter)
[![Super-Linter](https://github.com/<OWNER>/<REPOSITORY>/actions/workflows/<WORKFLOW_FILE_NAME>/badge.svg)](https://github.com/marketplace/actions/super-linter)
```
### Images
For more information, see
[Adding a workflow status badge](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge).
The **GitHub Super-Linter** now builds and supports `multiple` images. We have found as we added more linters, the image size expanded drastically.
After further investigation, we were able to see that a few linters were very disk heavy. We removed those linters and created the `slim` image.
This allows users to choose which **Super-Linter** they want to run and potentially speed up their build time.
The available images:
## Super-linter variants
- `super-linter/super-linter:v5`
- `super-linter/super-linter:slim-v5`
Super-Linter provides several variants:
#### Standard Image
- `standard`: `super-linter/super-linter:[VERSION]`: includes all supported linters.
- `slim`: `super-linter/super-linter:slim-[VERSION]`: includes all supported linters except:
The standard `super-linter/super-linter:v5` comes with all supported linters.
Example usage:
- `rust` linters
- `dotenv` linters
- `armttk` linters
- `pwsh` linters
- `c#` linters
```yml
################################
# Run Linter against code base #
################################
- name: Lint Code Base
uses: super-linter/super-linter@v5
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
## Configure super-linter
#### Slim Image
You can configure super-linter using the following environment variables:
The slim `super-linter/super-linter:slim-v5` comes with all supported linters but removes the following:
- `rust` linters
- `dotenv` linters
- `armttk` linters
- `pwsh` linters
- `c#` linters
By removing these linters, we were able to bring the image size down by `2gb` and drastically speed up the build and download time.
The behavior will be the same for non-supported languages, and will skip languages at runtime.
Example usage:
```yml
################################
# Run Linter against code base #
################################
- name: Lint Code Base
uses: super-linter/super-linter/slim@v5
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
## Environment variables
The super-linter allows you to pass the following `ENV` variables to be able to trigger different functionality.
_Note:_ All the `VALIDATE_[LANGUAGE]` variables behave in a very specific way:
- If none of them are passed, then they all default to true.
- If any one of the variables are set to true, we default to leaving any unset variable to false (only validate those languages).
- If any one of the variables are set to false, we default to leaving any unset variable to true (only exclude those languages).
- If there are `VALIDATE_[LANGUAGE]` variables set to both true and false. It will fail.
This means that if you run the linter "out of the box", all languages will be checked.
But if you wish to select or exclude specific linters, we give you full control to choose which linters are run, and won't run anything unexpected.
| **ENV VAR** | **Default Value** | **Notes** |
| **Environment variable** | **Default Value** | **Description** |
|-------------------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **ACTIONS_RUNNER_DEBUG** | `false` | Flag to enable additional information about the linter, versions, and additional output. |
| **ANSIBLE_CONFIG_FILE** | `.ansible-lint.yml` | Filename for [Ansible-lint configuration](https://ansible.readthedocs.io/projects/lint/configuring/) (ex: `.ansible-lint`, `.ansible-lint.yml`) |
@ -310,7 +186,7 @@ But if you wish to select or exclude specific linters, we give you full control
| **NATURAL_LANGUAGE_CONFIG_FILE** | `.textlintrc` | Filename for [textlint configuration](https://textlint.github.io/docs/getting-started.html#configuration) (ex: `.textlintrc`) |
| **PERL_PERLCRITIC_OPTIONS** | `null` | Additional arguments to pass to the command-line when running **perlcritic** (Example: --theme community) |
| **PHP_CONFIG_FILE** | `php.ini` | Filename for [PHP Configuration](https://www.php.net/manual/en/configuration.file.php) (ex: `php.ini`) |
| **PHP_PHPCS_FILE_NAME** | `phpcs.xml` | Filename for [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) (ex: `.phpcs.xml`, `.phpcs.xml.dist`) |
| **PHP_PHPCS_FILE_NAME** | `phpcs.xml` | Filename for [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) (ex: `.phpcs.xml`, `.phpcs.xml.dist`) |
| **PROTOBUF_CONFIG_FILE** | `.protolintrc.yml` | Filename for [protolint configuration](https://github.com/yoheimuta/protolint/blob/master/_example/config/.protolint.yaml) (ex: `.protolintrc.yml`) |
| **PYTHON_BLACK_CONFIG_FILE** | `.python-black` | Filename for [black configuration](https://github.com/psf/black/blob/main/docs/guides/using_black_with_other_tools.md#black-compatible-configurations) (ex: `.isort.cfg`, `pyproject.toml`) |
| **PYTHON_FLAKE8_CONFIG_FILE** | `.flake8` | Filename for [flake8 configuration](https://flake8.pycqa.org/en/latest/user/configuration.html) (ex: `.flake8`, `tox.ini`) |
@ -415,167 +291,120 @@ But if you wish to select or exclude specific linters, we give you full control
| **YAML_CONFIG_FILE** | `.yaml-lint.yml` | Filename for [Yamllint configuration](https://yamllint.readthedocs.io/en/stable/configuration.html) (ex: `.yaml-lint.yml`, `.yamllint.yml`) |
| **YAML_ERROR_ON_WARNING** | `false` | Flag to enable or disable the error on warning for Yamllint. |
### Template rules files
The `VALIDATE_[LANGUAGE]` variables work as follows:
You can use the **GitHub** **Super-Linter** _with_ or _without_ your own personal rules sets. This allows for greater flexibility for each individual codebase. The Template rules all try to follow the standards we believe should be enabled at the basic level.
- super-linter runs all supported linters by default.
- If you set any of the `VALIDATE_[LANGUAGE]` variables to `true`, super-linter defaults to leaving any unset variable to false (only validate those languages).
- If you set any of the `VALIDATE_[LANGUAGE]` variables to `false`, super-linter defaults to leaving any unset variable to true (only exclude those languages).
- If you set any of the `VALIDATE_[LANGUAGE]` variables to both `true` and `false`, super-linter fails reporting an error.
- Copy **any** or **all** template rules files from `TEMPLATES/` into the `.github/linters/` directory of your repository, and modify them to suit your needs.
- The rules files in [this repository's `TEMPLATE` folder](https://github.com/super-linter/super-linter/tree/main/TEMPLATES) will be used as defaults should any be omitted.
For more information about reusing super-linter configuration across
environments, see
[Share Environment variables between environments](docs/run-linter-locally.md#share-environment-variables-between-environments).
### Using your own rules files
## Configure linters
If your repository contains your own rules files that live outside of a `.github/linters/` directory, you will have to tell Super-Linter where your rules files are located in your repository, and what their filenames are. To learn more, see [Using your own rules files](docs/using-rules-files.md).
Super-linter provides default configurations for some linters in the [`TEMPLATES/`](TEMPLATES/)
directory. You can customize the configuration for the linters that support
this by placing your own configuration files in the `LINTER_RULES_PATH`
directory. `LINTER_RULES_PATH` is relative to the `DEFAULT_WORKSPACE` directory.
### Disabling rules
Super-linter supports customizing the name of these configuration files. For
more information, refer to [Configure super-linter](#configure-super-linter).
If you need to disable certain _rules_ and _functionality_, you can view [Disable Rules](https://github.com/super-linter/super-linter/blob/main/docs/disabling-linters.md)
For example, you can configure super-linter to load configuration files from the
`config/lint` directory in your repository:
### Using your own SSH key
If you need to add your own SSH key to the linter because of private dependencies, you can use the `SSH_KEY` environment
variable. The value of that environment variable should be an SSH private key that has access to your private
repositories.
You should add this key as an [Encrypted Secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
and access it with the `secrets` parameter.
Example workflow:
```yml
---
#################################
#################################
## Super Linter GitHub Actions ##
#################################
#################################
name: Lint Code Base
#############################
# Start the job on all push #
#############################
on:
push:
branches-ignore: [master, main]
# Remove the line above to run when pushing to master or main
pull_request:
branches: [master, main]
###############
# Set the Job #
###############
jobs:
build:
# Name the Job
name: Lint Code Base
# Set the agent to run on
runs-on: ubuntu-latest
##################
# Load all steps #
##################
steps:
##########################
# Checkout the code base #
##########################
- name: Checkout Code
uses: actions/checkout@v4
with:
# Full git history is needed to get a proper list of changed files within `super-linter`
fetch-depth: 0
################################
# Run Linter against code base #
################################
- name: Lint Code Base
uses: super-linter/super-linter@v5
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
```yaml
env:
LINTER_RULES_PATH: `config/lint`
```
## Filter linted files
Some of the linters that super-linter provides can be configured to disable
certain rules or checks, and to ignore certain files or part of them.
If you need to lint only a folder or exclude some files from linting, you can use optional environment parameters `FILTER_REGEX_INCLUDE` and `FILTER_REGEX_EXCLUDE`
For more information about how to configure each linter, review
[their own documentation](#supported-linters-and-code-analyzers).
Examples:
## Include or exclude files from checks
- Lint only src folder: `FILTER_REGEX_INCLUDE: .*src/.*`
If you need to include or exclude directories from being checked, you can use
two environment variables: `FILTER_REGEX_INCLUDE` and `FILTER_REGEX_EXCLUDE`.
For example:
- Lint only the `src` folder: `FILTER_REGEX_INCLUDE: .*src/.*`
- Do not lint files inside test folder: `FILTER_REGEX_EXCLUDE: .*test/.*`
- Do not lint JavaScript files inside test folder: `FILTER_REGEX_EXCLUDE: .*test/.*.js`
<!-- This `README.md` has both markers in the text, so it is considered not generated. -->
Additionally when `IGNORE_GENERATED_FILES=true`, super-linter
ignores any file with `@generated` marker in it unless the file
also has `@not-generated` marker. `@generated` marker is
[used by Facebook](https://engineering.fb.com/2015/08/20/open-source/writing-code-that-writes-code-with-hack-codegen/)
and some other projects to mark generated files. For example, this
file is considered generated:
Additionally, if you set `IGNORE_GENERATED_FILES` to `true`, super-linter
ignores any file with `@generated` string in it, unless the file
also has `@not-generated` marker. For example, super-linter considers a file
with the following contents as generated:
```bash
#!/bin/sh
echo "@generated"
```
And this file is considered not generated:
while considers this file as not generated:
```bash
#!/bin/sh
echo "@generated" # @not-generated
```
Finally, you can set `IGNORE_GITIGNORED_FILES` to `true` to ignore a file if Git
ignores it too.
## Run Super-Linter outside GitHub Actions
### Local (troubleshooting/debugging/enhancements)
You don't need GitHub Actions to run super-linter. It supports several runtime
environments.
If you find that you need to run super-linter locally, you can follow the documentation at [Running super-linter locally](https://github.com/super-linter/super-linter/blob/main/docs/run-linter-locally.md)
### Run using a container runtime engine
Check out the [note](#how-it-works) in **How it Works** to understand more about the **Super-Linter** linting locally versus via continuous integration.
You can run super-linter outside GitHub Actions. For example, you can run
super-linter from a shell:
### Azure
```bash
docker run \
-e ACTIONS_RUNNER_DEBUG=true \
-e RUN_LOCAL=true \
-v /path/to/local/codebase:/tmp/lint \
ghcr.io/super-linter/super-linter:latest
```
Check out this [article](https://blog.tyang.org/2020/06/27/use-github-super-linter-in-azure-pipelines/)
For more information, see
[Run super-linter outside GitHub Actions](https://github.com/super-linter/super-linter/blob/main/docs/run-linter-locally.md).
### GitLab
## Use your own SSH key and certificate
Check out this [snippet](https://gitlab.com/snippets/1988376) and this Guided Exploration: [GitLab CI CD Extension for Super-Linter](https://gitlab.com/guided-explorations/ci-cd-plugin-extensions/ci-cd-plugin-extension-github-action-super-linter)
If you need to use your own SSH key to authenticate against private
repositories, you can use the `SSH_KEY` environment variable. The value of that
environment variable is expected to be be the private key of an SSH keypair that
has access to your private repositories.
### Codespaces and Visual Studio Code
For example, you can configure this private key as an
[Encrypted Secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
and access it with the `secrets` parameter from your GitHub Actions workflow:
You can checkout this repository using [GitHub Codespaces](https://github.com/features/codespaces/) and [Container Remote Development](https://code.visualstudio.com/docs/remote/containers), and debug the linter using the `Test Linter` task.
![Example](https://user-images.githubusercontent.com/15258962/85165778-2d2ce700-b21b-11ea-803e-3f6709d8e609.gif)
### SSL Certs
If you need to inject a SSL cert into the trust store, you will need to first copy the cert to **GitHub Secrets**
Once you have copied the plain text certificate into **GitHub Secrets**, you can use the variable `SSL_CERT_SECRET` to point the **Super-Linter** to the files contents.
Once found, it will load the certificate contents to a file, and to the trust store.
- Example workflow:
```yml
- name: Lint Code Base
uses: super-linter/super-linter@v5
```yaml
env:
SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
```
If you need to inject a SSL certificate into the trust store, you can use the
`SSL_CERT_SECRET` variable. The value of that variable is expected to be the
path to the files that contains a CA that can be used to valide the certificate:
```yaml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SSL_CERT_SECRET: ${{ secrets.ROOT_CA }}
```
## Limitations
Below are a list of the known limitations for the **GitHub Super-Linter**:
- Due to being completely packaged at runtime, you will not be able to update dependencies or change versions of the enclosed linters and binaries
- Additional details from `package.json` are not read by the **GitHub Super-Linter**
- Downloading additional codebases as dependencies from private repositories will fail due to lack of permissions
## How to contribute
If you would like to help contribute to this **GitHub** Action, please see [CONTRIBUTING](https://github.com/super-linter/super-linter/blob/main/.github/CONTRIBUTING.md)
---
### License
- [MIT License](https://github.com/super-linter/super-linter/blob/main/LICENSE)
If you would like to help contribute to super-linter, see
[CONTRIBUTING](https://github.com/super-linter/super-linter/blob/main/.github/CONTRIBUTING.md)

18
SECURITY.md
View file

@ -1,5 +1,17 @@
# Security Policy
# Reporting Security Issues
If you discover a security issue in this repository, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
The super-linter team and community take security bugs seriously. We appreciate
your efforts to responsibly disclose your findings, and will make every effort
to acknowledge your contributions.
Thanks for helping make GitHub Actions safe for everyone.
To report a security issue, please use the GitHub Security Advisory
["Report a Vulnerability"](https://github.com/super-linter/super-linter/security/advisories/new)
feature.
The super-linter team will send a response indicating the next steps in handling
your report. After the initial reply to your report, the security team will keep
you informed of the progress towards a fix and full announcement, and may ask
for additional information or guidance.
Report security bugs in third-party software to the person or team maintaining
the third-party software.

65
TEMPLATES/linter.yml
View file

@ -1,65 +0,0 @@
---
#################################
#################################
## Super Linter GitHub Actions ##
#################################
#################################
name: Lint Code Base
#
# Documentation:
# https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
#
#############################
# Start the job on all push #
#############################
on:
push:
branches-ignore: [master, main]
# Remove the line above to run when pushing to master
pull_request:
branches: [master, main]
###############
# Set the Job #
###############
jobs:
build:
# Name the Job
name: Lint Code Base
# Set the agent to run on
runs-on: ubuntu-latest
############################################
# Grant status permission for MULTI_STATUS #
############################################
permissions:
contents: read
packages: read
statuses: write
##################
# Load all steps #
##################
steps:
##########################
# Checkout the code base #
##########################
- name: Checkout Code
uses: actions/checkout@v3
with:
# Full git history is needed to get a proper
# list of changed files within `super-linter`
fetch-depth: 0
################################
# Run Linter against code base #
################################
- name: Lint Code Base
uses: super-linter/super-linter@v5
env:
VALIDATE_ALL_CODEBASE: false
# Change to 'master' if your main branch differs
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

15
docs/disabling-linters.md
View file

@ -1,15 +0,0 @@
# Disabling linters and Rules
Linters can often require additional configuration to ensure they work with your codebase and your team's coding style, to avoid flagging false-positives. The **GitHub Super-Linter** has set up some default configurations for each linter which should work reasonably well with common code bases, but many of the linters can be configured to disable certain rules or configure the rules to ignore certain pieces of codes.
To run with your own configuration for a linter, copy the relevant [`TEMPLATE` configuration file for the linter you are using from this repository](https://github.com/super-linter/super-linter/tree/main/TEMPLATES) into the `.github/linters/` folder in your own repository, and then edit it to modify, disable - or even add - rules and configuration to suit how you want your code checked.
How the changes are made differ for each linter, and also how much the **GitHub Super-Linter** has decided to change the linter's defaults. So, for some linters (e.g. [pylint for python](https://github.com/super-linter/super-linter/blob/main/TEMPLATES/.python-lint)), there may be a large configuration file. For others (e.g. [stylelint for CSS](https://github.com/super-linter/super-linter/blob/main/TEMPLATES/.stylelintrc.json)) the default configuration file may initially be nearly empty. And for some (e.g. StandardJS) it may not be possible to change configuration at all so there is no Template file.
Where a configuration file exists in your repository, it will be used in preference to the default one in the **GitHub Super-Linter** `TEMPLATES` directory (not in addition to it), and where one doesn't exist the `TEMPLATES` version will be used. So you should copy the complete configuration file you require to change from the `TEMPLATES` directory and not just the lines of config you want to change.
It is possible to have custom configurations for some linters, and continue to use the default from `TEMPLATES` directory for others, so if you use `Python` and `JavaScript` and only need to tweak the `Python` rules, then you only need to have a custom configuration for _pylint_ and continue to use the default `TEMPLATE` from the main repository for _ESLint_, for example.
For some linters it is also possible to override rules on a case by case level with directives in your code. Where this is possible we try to note how to do this in the specific linter sections below, but the official linter documentation will likely give more detail on this.
**NOTE: Please view each linters source and web page from the [Supported Linters README](https://github.com/super-linter/super-linter#supported-linters) to see additional information on how to configure, disable, or tune additional rules.**

141
docs/run-linter-locally.md
View file

@ -1,128 +1,84 @@
# Run Super-Linter locally to test your branch of code
# Run super-linter outside GitHub Actions
If you want to test locally against the **Super-Linter** to test your branch of
code or to reproduce an issue, do the following:
If you want to run super-linter outside GitHub Actions, you need a container
runtime engine to run the super-linter container image.
- Clone your testing source code to your local environment
- Install Docker to your local environment
- Pull the container
- Run the container locally
## Run super-linter Locally
If you're contributing to Super-Linter, you also need to do following:
- Run the test suite locally
## 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 image from the registry
- `docker pull ghcr.io/super-linter/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 flags to run your code:
You can run the container locally with the following configuration options to run your code:
```bash
docker run \
-e ACTIONS_RUNNER_DEBUG=true \
-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, **refer to a specific version instead**.
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` flag to bypass some of the GitHub Actions checks, as well as the mapping of your local codebase to `/tmp/lint`.
- 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.
- 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.
- Add the `--rm` docker flag to automatically removes the container after execution.
- You can add as many flags as needed. Flags are documented in the [README](../README.md#Environment-variables).
- You can add as many configuration options as needed. Configuration options are documented in the [README](../README.md#configure-super-linter).
## Sharing Environment variables between Local and CI
### Azure
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.
Check out this [article](https://blog.tyang.org/2020/06/27/use-github-super-linter-in-azure-pipelines/)
### .github/super-linter.env
### GitLab
This is the shared location for the super-linter variables. Example:
Check out this [snippet](https://gitlab.com/snippets/1988376) and this Guided Exploration: [GitLab CI CD Extension for Super-Linter](https://gitlab.com/guided-explorations/ci-cd-plugin-extensions/ci-cd-plugin-extension-github-action-super-linter)
```bash
VALIDATE_ALL_CODEBASE=true
VALIDATE_DOCKERFILE_HADOLINT=false
VALIDATE_EDITORCONFIG=false
VALIDATE_GITLEAKS=false
```
### Run on Codespaces and Visual Studio Code
### scripts/lint
This repository provides a DevContainer for [remote development](https://code.visualstudio.com/docs/remote/containers).
This always runs the local docker based linting.
## Share Environment variables between environments
```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
```
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:
### scripts/test
1. Create a configuration file for super-linter `super-linter.env`. For example:
This runs the local lint when not on CI.
```bash
VALIDATE_ALL_CODEBASE=true
```
```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
```
1. Load the super-linter configuration file when running outside GitHub Actions:
### .github/workflows/ci.yml
```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
```
This loads the environment variables before running the GitHub Actions job.
1. 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:
```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: main
```
```yaml
- name: Load super-linter configuration
run: cat .github/super-linter.env >> "$GITHUB_ENV"
```
## Build the container image and run the test suite locally
You can run the test suite locally with the following command:
You can run the build and test process locally with the following command:
```shell
make
```
The test suite will build the container image and run the test suite against a
a container that is an instance of that container image.
### Run the test suite against an arbitrary super-linter container image
You can run the test suite against an arbitrary super-linter container image.
@ -142,15 +98,10 @@ 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.
## Troubleshooting
### Get the list of available build targets
### Run container and gain access to the command-line
To get the list of the available `Make` targets, run the following command:
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 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.
### Found issues
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)
```shell
make help
```

30
docs/using-rules-files.md
View file

@ -1,30 +0,0 @@
# Using your own rules files
If your repository contains your own rules files that live outside of a ``.github/linters/`` directory, you will have to tell Super-Linter where your rules files are located in your repository, and what their filenames are.
You can tell Super-Linter where your rules files are located with the ``LINTER_RULES_PATH`` ENV VAR (this is relative to the ``DEFAULT_WORKSPACE``), and you can tell Super-Linter what their filenames are by using any of the filename ENV VARS listed in the [Environment variables table](/README.md#Environment-variables). You can determine which ENV VARS are filename ENV VARS by looking in the notes column for the term "filename."
## Here is an example
Below is an example of how to configure the ``env`` section of Super-Linter's ``linter.yml`` to lint JavaScript and CSS code using ``eslint`` and ``stylelint`` with your own ``.eslintrc.json`` and ``.stylelintrc.json`` rules files that are located in the root directory of your repository.
``` yaml
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LINTER_RULES_PATH: /
CSS_FILE_NAME: .stylelintrc.json
JAVASCRIPT_ES_CONFIG_FILE: .eslintrc.json
VALIDATE_CSS: true
VALIDATE_JAVASCRIPT_ES: true
```
The above example tells Super-Linter:
a) Your rules files are located in your repository's root directory using the ``LINTER_RULES_PATH: /`` ENV VAR.
b) Your ESLint and stylelint rules files are named ``.stylelintrc.json`` and ``.eslintrc.json`` using the ``CSS_FILE_NAME: .styelintrc.json`` and ``JAVASCRIPT_ES_CONFIG_FILE: .eslintrc.json`` ENV VARS.
c) To use ``stylelint`` and ``eslint`` to lint all CSS and JavaScript code using the ``VALIDATE_CSS: true`` and ``VALIDATE_JAVASCRIPT_ES: true`` ENV VARS.

1
test/inspec/super-linter/controls/super_linter.rb
View file

@ -402,7 +402,6 @@ control "super-linter-validate-files" do
"/action/lib/.automation/.tflint.hcl",
"/action/lib/.automation/.yaml-lint.yml",
"/action/lib/.automation/analysis_options.yml",
"/action/lib/.automation/linter.yml",
"/action/lib/.automation/phpcs.xml",
"/action/lib/.automation/phpstan.neon",
"/action/lib/.automation/psalm.xml",