From 08ee1c043aa41b80a6c4359ec97fd3426c2b3b09 Mon Sep 17 00:00:00 2001
From: "Mr. Walls" <reactive-firewall@users.noreply.github.com>
Date: Fri, 20 Dec 2024 20:36:05 -0800
Subject: [PATCH] Updated with more comprehensive documentation and alternative
 GHA options

---
 GitHub-Actions.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)

diff --git a/GitHub-Actions.md b/GitHub-Actions.md
index 7e3e19b..88757cf 100644
--- a/GitHub-Actions.md
+++ b/GitHub-Actions.md
@@ -1,3 +1,47 @@
+# GitHub Actions
+
+GitHub Actions is a powerful automation platform that can run ShellCheck against your shell scripts. ShellCheck is pre-installed on GitHub's Ubuntu runners, making it easy to integrate into your workflows.
+
+## Basic Usage
+
+The simplest way to run ShellCheck is directly using the pre-installed binary:
+
+```yaml
+name: "ShellCheck"
+on: [push, pull_request]
+
+jobs:
+  shellcheck:
+    name: ShellCheck
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Run ShellCheck
+      run: shellcheck **/*.sh
+```
+
+## GitHub Advanced Security Integration
+
+To use ShellCheck with GitHub Advanced Security code scanning, you can use [shellcheck-scan](https://github.com/marketplace/actions/shellcheck-sarif-analysis) which generates SARIF reports:
+
+```yaml
+name: ShellCheck SARIF
+on: [push, pull_request]
+
+jobs:
+  scan:
+    name: ShellCheck Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write  # required for uploading SARIF results
+      actions: read          # only required for workflows in private repositories
+      contents: read
+    steps:
+    - uses: actions/checkout@v4
+    - name: Run ShellCheck with SARIF output
+      uses: reactive-firewall/shellcheck-scan@v1
+```
+
 ## Differential ShellCheck
 
 GitHub action for running ShellCheck differentially. New findings are reported directly at GitHub pull requests (using SARIF format).
@@ -40,3 +84,77 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 ```
+
+## Advanced Configuration
+
+### Customizing ShellCheck Options
+
+ShellCheck supports various options that can be used in your workflow:
+
+```yaml
+- name: Run ShellCheck
+  run: |
+    shellcheck \
+      --severity=warning \  # Set minimum severity
+      --shell=bash \       # Specify shell dialect
+      --format=gcc \       # Set output format
+      **/*.sh
+```
+
+### Common Options
+
+- `-S [error|warning|info|style]`: Set minimum severity of errors to consider
+- `-s [sh|bash|dash|ksh]`: Specify shell dialect
+- `-e [SC1234,SC2345]`: Exclude specific error codes
+- `-f [checkstyle|diff|gcc|json|quiet|tty]`: Set output format
+
+### Version Pinning
+
+To ensure reproducible builds, you can pin to a specific ShellCheck version:
+
+```yaml
+- name: Install specific ShellCheck version
+  run: |
+    wget https://github.com/koalaman/shellcheck/releases/download/v0.9.0/shellcheck-v0.9.0.linux.x86_64.tar.xz
+    tar -xf shellcheck-v0.9.0.linux.x86_64.tar.xz
+    sudo cp shellcheck-v0.9.0/shellcheck /usr/bin/
+```
+
+## Example Configurations
+
+### Check All Shell Scripts
+
+```yaml
+- name: Run ShellCheck
+  run: find . -type f -name "*.sh" -exec shellcheck {} +
+```
+
+### Using with Matrix Strategy
+
+```yaml
+jobs:
+  shellcheck:
+    strategy:
+      matrix:
+        shell: [bash, sh, dash, ksh]
+    steps:
+    - name: Run ShellCheck
+      run: shellcheck --shell=${{ matrix.shell }} **/*.sh
+```
+
+### Selective Checking
+
+```yaml
+- name: Check scripts in specific directory
+  run: shellcheck scripts/*.sh src/scripts/*.sh
+```
+
+## Additional Resources
+
+- [ShellCheck Documentation](https://github.com/koalaman/shellcheck)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [shellcheck-scan Action](https://github.com/marketplace/actions/shellcheck-sarif-analysis)
+- [@redhat-plumbers-in-action/differential-shellcheck](https://github.com/redhat-plumbers-in-action/differential-shellcheck)
+
+---
+_Last updated: 2024-12-21 by [@reactive-firewall](https://github.com/reactive-firewall)_
\ No newline at end of file