From a5c0cf27db3814f553f231eabc2093294b13e169 Mon Sep 17 00:00:00 2001
From: Marco Ferrari <ferrari.marco@gmail.com>
Date: Sun, 25 Aug 2024 14:47:45 +0200
Subject: [PATCH] docs: add an example about fix mode on gh actions (#6060)

---
 README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)

diff --git a/README.md b/README.md
index f2cadc1b..94aaeeec 100644
--- a/README.md
+++ b/README.md
@@ -463,6 +463,104 @@ When fix mode is enabled, some linters and formatters don't maintain the
 original file or directory ownership, and use the user that Super-linter uses
 to run the linter or formatter.
 
+### Fix mode examples and workflows
+
+You can configure Super-linter to automatically deliver linting and formatting
+fixes. For example, you can configure a workflow that automatically commits the
+fixes, and pushes them to a branch.
+
+To ensure that Super-linter analyzes your codebase as expected, we recommend
+that you configure your fix mode workflows in addition to your existing
+Super-linter workflows.
+
+#### GitHub Actions workflow example: pull request
+
+The following example shows a GitHub Actions workflow that uses Super-linter to
+automatically fix linting and formatting issues, commit changes in the current
+branch, and push commits to the remote branch tracking the current branch
+whenever a pull request is created or updated:
+
+```yaml
+---
+name: Lint
+
+on: # yamllint disable-line rule:truthy
+  push: null
+  pull_request: null
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    # Super-linter workflow running in check only mode
+    # See https://github.com/super-linter/super-linter#get-started
+
+  fix-lint-issues:
+    permissions:
+      # To write linting fixes
+      contents: write
+      # To write Super-linter status checks
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Super-Linter
+        uses: super-linter/super-linter@v7.0.0 # x-release-please-version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Set your fix mode variables to true
+          FIX_SHELL_SHFMT: true
+          FIX_YAML_PRETTIER: true
+          # To reuse the same Super-linter configuration that you use in the
+          # lint job without duplicating it, see
+          # https://github.com/super-linter/super-linter/blob/main/docs/run-linter-locally.md#share-environment-variables-between-environments
+      - name: Commit and push linting fixes
+        # Run only on:
+        # - Pull requests
+        # - Not on the default branch
+        if: >
+          github.event_name == 'pull_request' &&
+          github.ref_name != github.event.repository.default_branch
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}
+          commit_message: "chore: fix linting issues"
+          commit_user_name: super-linter
+          commit_user_email: super-linter@super-linter.dev
+```
+
+This example uses
+[GitHub Actions automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication)
+that automatically greates a unique `GITHUB_TOKEN` secret for the workflow.
+GitHub Actions imposes the following limitations on workflows:
+
+- To avoid accidentally creating recursive workflow runs, the commit that
+  contains linting and formatting fixes
+  [doesn't create new workflow runs](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
+- It restrict edits to GitHub Actions workflows files (in `.github/workflows`).
+- It may fail pushing commits to protected branches.
+
+To work around these limitations, you do the following:
+
+1. [Create an authentication token with additional permissions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#granting-additional-permissions).
+1. Grant the authentication token the
+   [`repo` and `workflow` permissions](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens).
+1. Use the authentication token in the `actions/checkout` step:
+
+   ```yaml
+   - uses: actions/checkout@v4
+     with:
+       fetch-depth: 0
+       token: ${{ secrets.SUPER_LINTER_TOKEN }}
+   ```
+
+   This example assumes that you saved the authentication token in a secret
+   called `SUPER_LINTER_TOKEN`, but you can choose whatever name you prefer for
+   the secret.
+
 ## Configure linters
 
 Super-linter provides default configurations for some linters in the [`TEMPLATES/`](./TEMPLATES/)
@@ -610,6 +708,21 @@ previous paragraph, but only supports emitting results to standard output or
 standard error streams, you can
 [enable Super-linter outputs](#super-linter-outputs) and parse them.
 
+### Ignore output that Super-linter generates
+
+Super-linter generates output reports and logs. To avoid that these outputs end
+up in your repository, we recommend that you add the following lines to your
+`.gitignore` file:
+
+```text
+# Super-linter outputs
+super-linter-output
+super-linter.log
+
+# GitHub Actions leftovers
+github_conf
+```
+
 ## How to contribute
 
 If you would like to help contribute to super-linter, see