docs: Add samples

.husky/pre-commit

@@ -2,4 +2,4 @@
 . "$(dirname "$0")/_/husky.sh"
 (cd internal/run && NODE_OPTIONS=--openssl-legacy-provider npm run build && git add dist/)
 (cd setup && NODE_OPTIONS=--openssl-legacy-provider npm run build && git add dist/)
-doc-resources/update-doc-resources.sh
+doc-resources/update-repo-docs.sh

CONTRIBUTING.md

@@ -19,6 +19,7 @@ Action documentation is generated from the `doc-resources` directory, using func
 * `templates/<action-name>/README.template.md`: Template for the README.md file for each action
 * `action-<action-name>.md`: Documentation for each action, included by both the corresponding action readme template, and the top-level readme (through `repo-readme.md`)
 * `env-*.md`: Documentation for the environment variables supported by the various actions. Most of these are named after the action that they correspond to, for example `env-fod-login.md` (corresponding to the `internal/fod-login` action), listing action-specific environment variables. Others describe generic environment variables that are shared by multiple actions, for example `env-fod-release.md`.
+* `nocomments.env-*-sample.md`: Most of the `env-*.md` files mentioned above have a corresponding sample file that shows how to configure the variables in a GitHub workflow.
 * `repo-devinfo.md`: Information for developers
 * `repo-readme.md`: Top-level readme contents
 * `repo-usage.md`: Used to generated top-level USAGE.md, just refers to README.md

README.md

@@ -138,7 +138,7 @@ The sample workflow below demonstrates how to configure the action for installin
 
 <!-- START-INCLUDE:action-package.md -->
 
-This action packages application source code to be scanned using [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2310/SC_SAST_Help_23.1.0/index.htm#A_Clients.htm).
+This action packages application source code using [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2310/SC_SAST_Help_23.1.0/index.htm#A_Clients.htm). The output package is saved as `package.zip`.
 
 ### Action environment variable inputs
 
@@ -151,6 +151,20 @@ Optional: By default, this action runs `scancentral package -o package.zip`. The
 <!-- END-INCLUDE:env-package.md -->
 
 
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
+
+```yaml
+    steps:  
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Package source code
+        uses: fortify/github-action/package@v1
+        env:
+          EXTRA_PACKAGE_OPTS: -bt mvn
+```
+
 <!-- END-INCLUDE:action-package.md -->
 
 
@@ -178,6 +192,9 @@ Before running this action, please ensure that the appropriate release has been
 
 <!-- START-INCLUDE:env-fod-login.md -->
 
+
+<!-- START-INCLUDE:env-fod-connection.md -->
+
 **`FOD_URL`**    
 Required: Fortify on Demand URL, for example https://ams.fortify.com
 
@@ -187,6 +204,9 @@ Required when authenticating with an API key: FoD Client ID (API key) and Secret
 **`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`**   
 Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password.
 
+<!-- END-INCLUDE:env-fod-connection.md -->
+
+
 **`EXTRA_FOD_LOGIN_OPTS`**    
 Optional: Extra FoD login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation](https://fortify.github.io/fcli/v2.0.0//manpage/fcli-fod-session-login.html)
 
@@ -223,6 +243,28 @@ Optional: If set to `true`, this action will export scan results to the GitHub S
 <!-- END-INCLUDE:env-fod-sast-scan.md -->
 
 
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
+
+```yaml
+    steps:    
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Run FoD SAST Scan
+        uses: fortify/github-action/fod-sast-scan@v1
+        env:
+          FOD_URL: https://ams.fortify.com
+          FOD_TENANT: ${{secrets.FOD_TENANT}}
+          FOD_USER: ${{secrets.FOD_USER}}
+          FOD_PASSWORD: ${{secrets.FOD_PAT}}
+          EXTRA_FOD_LOGIN_OPTS: --socket-timeout=60s
+          FOD_RELEASE: MyApp:MyRelease
+          EXTRA_PACKAGE_OPTS: -oss -bt gradle
+          # DO_WAIT: true # Ignored due to DO_EXPORT below
+          DO_EXPORT: true
+```
+
 <!-- END-INCLUDE:action-fod-sast-scan.md -->
 
 
@@ -236,7 +278,7 @@ This action exports the latest vulnerability data from an FoD release to the Git
 ### Action environment variable inputs
 
 
-<!-- START-INCLUDE:env-fod-login.md -->
+<!-- START-INCLUDE:env-fod-connection.md -->
 
 **`FOD_URL`**    
 Required: Fortify on Demand URL, for example https://ams.fortify.com
@@ -247,10 +289,7 @@ Required when authenticating with an API key: FoD Client ID (API key) and Secret
 **`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`**   
 Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password.
 
-**`EXTRA_FOD_LOGIN_OPTS`**    
-Optional: Extra FoD login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation](https://fortify.github.io/fcli/v2.0.0//manpage/fcli-fod-session-login.html)
-
-<!-- END-INCLUDE:env-fod-login.md -->
+<!-- END-INCLUDE:env-fod-connection.md -->
 
 
 
@@ -262,6 +301,22 @@ Required: Fortify on Demand release to use with this action. This can be specifi
 <!-- END-INCLUDE:env-fod-release.md -->
 
 
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for exporting FoD vulnerability data to the GitHub Security Code Scanning dashboard.
+
+```yaml
+    steps:    
+      - name: Export FoD vulnerability data to GitHub
+        uses: fortify/github-action/fod-export@v1
+        env:
+          FOD_URL: https://ams.fortify.com
+          FOD_TENANT: ${{secrets.FOD_TENANT}}
+          FOD_USER: ${{secrets.FOD_USER}}
+          FOD_PASSWORD: ${{secrets.FOD_PAT}}
+          FOD_RELEASE: MyApp:MyRelease
+```
+
 <!-- END-INCLUDE:action-fod-export.md -->
 
 
@@ -343,6 +398,27 @@ Optional: If set to `true`, this action will export scan results to the GitHub S
 <!-- END-INCLUDE:env-sc-sast-scan.md -->
 
 
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for running a SAST scan on ScanCentral SAST.
+
+```yaml
+    steps:    
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Run ScanCentral SAST Scan
+        uses: fortify/github-action/sc-sast-scan@v1
+        env:
+          SSC_URL: ${{secrets.SSC_URL}}
+          SSC_TOKEN: ${{secrets.SSC_TOKEN}}
+          SC_SAST_CLIENT_AUTH_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}}
+          EXTRA_SC_SAST_LOGIN_OPTS: --socket-timeout=60s
+          SSC_APPVERSION: MyApp:MyVersion
+          EXTRA_PACKAGE_OPTS: -bt mvn
+          # DO_WAIT: true # Ignored due to DO_EXPORT below
+          DO_EXPORT: true
+```
+
 <!-- END-INCLUDE:action-sc-sast-scan.md -->
 
 
@@ -356,9 +432,6 @@ This action exports the latest vulnerability data from an SSC application versio
 ### Action environment variable inputs
 
 
-<!-- START-INCLUDE:env-ssc-login.md -->
-
-
 <!-- START-INCLUDE:env-ssc-connection.md -->
 
 **`SSC_URL`**    
@@ -373,12 +446,6 @@ Required when authenticating with user credentials.
 <!-- END-INCLUDE:env-ssc-connection.md -->
 
 
-**`EXTRA_SSC_LOGIN_OPTS`**    
-Optional: Extra SSC login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli ssc session login` documentation](https://fortify.github.io/fcli/v2.0.0//manpage/fcli-ssc-session-login.html).
-
-<!-- END-INCLUDE:env-ssc-login.md -->
-
-
 
 <!-- START-INCLUDE:env-ssc-appversion.md -->
 
@@ -388,6 +455,20 @@ Required: Fortify SSC application version to use with this action. This can be s
 <!-- END-INCLUDE:env-ssc-appversion.md -->
 
 
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for exporting FoD vulnerability data to the GitHub Security Code Scanning dashboard.
+
+```yaml
+    steps:    
+      - name: Export SSC vulnerability data to GitHub
+        uses: fortify/github-action/ssc-export@v1
+        env:
+          SSC_URL: ${{secrets.SSC_URL}}
+          SSC_TOKEN: ${{secrets.SSC_TOKEN}}
+          SSC_APPVERSION: MyApp:MyVersion
+```
+
 <!-- END-INCLUDE:action-ssc-export.md -->
 
 

doc-resources/action-fod-export.md

@@ -2,6 +2,19 @@ This action exports the latest vulnerability data from an FoD release to the Git
 
 ### Action environment variable inputs
 
-{{include:env-fod-login.md}}
+{{include:env-fod-connection.md}}
 
 {{include:env-fod-release.md}}
+
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for exporting FoD vulnerability data to the GitHub Security Code Scanning dashboard.
+
+```yaml
+    steps:    
+      - name: Export FoD vulnerability data to GitHub
+        uses: fortify/github-action/fod-export@{{var:action-major-version}}
+        env:
+{{include:nocomments.env-fod-connection-sample.md}}
+{{include:nocomments.env-fod-release-sample.md}}
+```

doc-resources/action-fod-sast-scan.md

@@ -11,3 +11,17 @@ Before running this action, please ensure that the appropriate release has been
 ### Action environment variable inputs
 
 {{include:env-fod-sast-scan.md}}
+
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
+
+```yaml
+    steps:    
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Run FoD SAST Scan
+        uses: fortify/github-action/fod-sast-scan@{{var:action-major-version}}
+        env:
+{{include:nocomments.env-fod-sast-scan-sample.md}}
+```

doc-resources/action-package.md

@@ -1,5 +1,19 @@
-This action packages application source code to be scanned using [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm).
+This action packages application source code using [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm). The output package is saved as `package.zip`.
 
 ### Action environment variable inputs
 
-{{include:env-package.md}}
+{{include:env-package.md}}
+
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
+
+```yaml
+    steps:  
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Package source code
+        uses: fortify/github-action/package@{{var:action-major-version}}
+        env:
+{{include:nocomments.env-package-sample.md}}
+```

doc-resources/action-sc-sast-scan.md

@@ -10,4 +10,18 @@ Before running this action, please ensure that the appropriate application versi
 
 ### Action environment variable inputs
 
-{{include:env-sc-sast-scan.md}}
+{{include:env-sc-sast-scan.md}}
+
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for running a SAST scan on ScanCentral SAST.
+
+```yaml
+    steps:    
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Run ScanCentral SAST Scan
+        uses: fortify/github-action/sc-sast-scan@{{var:action-major-version}}
+        env:
+{{include:nocomments.env-sc-sast-scan-sample.md}}
+```

doc-resources/action-ssc-export.md

@@ -2,6 +2,19 @@ This action exports the latest vulnerability data from an SSC application versio
 
 ### Action environment variable inputs
 
-{{include:env-ssc-login.md}}
+{{include:env-ssc-connection.md}}
 
 {{include:env-ssc-appversion.md}}
+
+### Sample usage
+
+The sample workflow below demonstrates how to configure the action for exporting FoD vulnerability data to the GitHub Security Code Scanning dashboard.
+
+```yaml
+    steps:    
+      - name: Export SSC vulnerability data to GitHub
+        uses: fortify/github-action/ssc-export@{{var:action-major-version}}
+        env:
+{{include:nocomments.env-ssc-connection-sample.md}}
+{{include:nocomments.env-ssc-appversion-sample.md}}
+```

doc-resources/env-fod-connection.md

@@ -0,0 +1,8 @@
+**`FOD_URL`**    
+Required: Fortify on Demand URL, for example https://ams.fortify.com
+
+**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`**   
+Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret)
+
+**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`**   
+Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password.

doc-resources/env-fod-login.md

@@ -1,11 +1,4 @@
-**`FOD_URL`**    
-Required: Fortify on Demand URL, for example https://ams.fortify.com
-
-**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`**   
-Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret)
-
-**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`**   
-Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password.
+{{include:env-fod-connection.md}}
 
 **`EXTRA_FOD_LOGIN_OPTS`**    
 Optional: Extra FoD login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-fod-session-login.html)

doc-resources/nocomments.env-fod-connection-sample.md

@@ -0,0 +1,4 @@
+          FOD_URL: https://ams.fortify.com
+          FOD_TENANT: ${{secrets.FOD_TENANT}}
+          FOD_USER: ${{secrets.FOD_USER}}
+          FOD_PASSWORD: ${{secrets.FOD_PAT}}

doc-resources/nocomments.env-fod-login-sample.md

@@ -0,0 +1,2 @@
+{{include:nocomments.env-fod-connection-sample.md}}
+          EXTRA_FOD_LOGIN_OPTS: --socket-timeout=60s

doc-resources/nocomments.env-fod-package-sample.md

@@ -0,0 +1 @@
+          EXTRA_PACKAGE_OPTS: -oss -bt gradle

doc-resources/nocomments.env-fod-release-sample.md

@@ -0,0 +1 @@
+          FOD_RELEASE: MyApp:MyRelease

doc-resources/nocomments.env-fod-sast-scan-sample.md

@@ -0,0 +1,5 @@
+{{include:nocomments.env-fod-login-sample.md}}
+{{include:nocomments.env-fod-release-sample.md}}
+{{include:nocomments.env-fod-package-sample.md}}
+          # DO_WAIT: true # Ignored due to DO_EXPORT below
+          DO_EXPORT: true

doc-resources/nocomments.env-package-sample.md

@@ -0,0 +1 @@
+          EXTRA_PACKAGE_OPTS: -bt mvn

doc-resources/nocomments.env-sc-sast-login-sample.md

@@ -0,0 +1,3 @@
+{{include:nocomments.env-ssc-connection-sample.md}}
+          SC_SAST_CLIENT_AUTH_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}}
+          EXTRA_SC_SAST_LOGIN_OPTS: --socket-timeout=60s

doc-resources/nocomments.env-sc-sast-scan-sample.md

@@ -0,0 +1,5 @@
+{{include:nocomments.env-sc-sast-login-sample.md}}
+{{include:nocomments.env-ssc-appversion-sample.md}}
+{{include:nocomments.env-package-sample.md}}
+          # DO_WAIT: true # Ignored due to DO_EXPORT below
+          DO_EXPORT: true

doc-resources/nocomments.env-ssc-appversion-sample.md

@@ -0,0 +1 @@
+          SSC_APPVERSION: MyApp:MyVersion

doc-resources/nocomments.env-ssc-connection-sample.md

@@ -0,0 +1,2 @@
+          SSC_URL: ${{secrets.SSC_URL}}
+          SSC_TOKEN: ${{secrets.SSC_TOKEN}}

doc-resources/repo-devinfo.md

@@ -10,6 +10,7 @@ Action documentation is generated from the `doc-resources` directory, using func
 * `templates/<action-name>/README.template.md`: Template for the README.md file for each action
 * `action-<action-name>.md`: Documentation for each action, included by both the corresponding action readme template, and the top-level readme (through `repo-readme.md`)
 * `env-*.md`: Documentation for the environment variables supported by the various actions. Most of these are named after the action that they correspond to, for example `env-fod-login.md` (corresponding to the `internal/fod-login` action), listing action-specific environment variables. Others describe generic environment variables that are shared by multiple actions, for example `env-fod-release.md`.
+* `nocomments.env-*-sample.md`: Most of the `env-*.md` files mentioned above have a corresponding sample file that shows how to configure the variables in a GitHub workflow.
 * `repo-devinfo.md`: Information for developers
 * `repo-readme.md`: Top-level readme contents
 * `repo-usage.md`: Used to generated top-level USAGE.md, just refers to README.md