mirror of
https://github.com/super-linter/super-linter.git
synced 2024-11-21 05:31:06 -05:00
Update documentation (#4981)
* 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
GitHub
parent
037997ac19
commit
d465382ed5
8 changed files with 211 additions and 569 deletions
65
.github/CONTRIBUTING.md
vendored
65
.github/CONTRIBUTING.md
vendored
|
|
@ -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
|
||||
|
|
|
|||
417
README.md
417
README.md
|
|
@ -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)
|
||||
[](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:
|
||||
|
||||
- `.github/workflows/linter.yml`
|
||||
- Example file can be found at [`TEMPLATES/linter.yml`](TEMPLATES/linter.yml)
|
||||
|
||||
This file should have the following code:
|
||||
|
||||
```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:
|
||||
jobs:
|
||||
build:
|
||||
# Name the Job
|
||||
name: Lint Code Base
|
||||
# Set the agent to run on
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
############################################
|
||||
# Grant status permission for MULTI_STATUS #
|
||||
############################################
|
||||
permissions:
|
||||
contents: read
|
||||
packages: read
|
||||
# To report GitHub Actions status checks
|
||||
statuses: write
|
||||
|
||||
##################
|
||||
# Load all steps #
|
||||
##################
|
||||
steps:
|
||||
##########################
|
||||
# Checkout the code base #
|
||||
##########################
|
||||
- name: Checkout Code
|
||||
- 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
|
||||
- name: Super-linter
|
||||
uses: super-linter/super-linter@v5
|
||||
env:
|
||||
VALIDATE_ALL_CODEBASE: false
|
||||
DEFAULT_BRANCH: main
|
||||
# To report GitHub Actions status checks
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
...
|
||||
```
|
||||
|
||||
### Add Super-Linter badge in your repository README
|
||||
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.
|
||||
|
||||
You can show Super-Linter status with a badge in your repository README
|
||||
## Add Super-Linter badge in your repository README
|
||||
|
||||
[](https://github.com/marketplace/actions/super-linter)
|
||||
|
||||
Format:
|
||||
|
||||
```markdown
|
||||
[](https://github.com/marketplace/actions/super-linter)
|
||||
```
|
||||
You can show Super-Linter status with a badge in your repository README:
|
||||
|
||||
Example:
|
||||
|
||||
```markdown
|
||||
[](https://github.com/marketplace/actions/super-linter)
|
||||
[](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`) |
|
||||
|
|
@ -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
|
||||
```yaml
|
||||
env:
|
||||
VALIDATE_ALL_CODEBASE: false
|
||||
DEFAULT_BRANCH: main
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
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.
|
||||
|
||||
|
||||
### 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
18
SECURITY.md
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 }}
|
||||
|
|
@ -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.**
|
||||
|
|
@ -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 \
|
||||
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:
|
||||
|
||||
```bash
|
||||
VALIDATE_ALL_CODEBASE=true
|
||||
```
|
||||
|
||||
1. Load the super-linter configuration file when running outside GitHub Actions:
|
||||
|
||||
```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
|
||||
```
|
||||
-v "$(pwd)":/tmp/lint \
|
||||
ghcr.io/super-linter/super-linter:latest
|
||||
```
|
||||
|
||||
### scripts/test
|
||||
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:
|
||||
|
||||
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: 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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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",
|
||||
|
|
|
|||
Loading…
Reference in a new issue