docs: improve actions security documentation (#1018)

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>

Author: moe-ad

check-actions-security/zizmor.yml

@@ -0,0 +1,28 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+rules:
+  unpinned-uses:
+    config:
+      policies:
+        ansys/*: ref-pin
+        actions/*: hash-pin

doc/source/changelog/1018.documentation.md

@@ -0,0 +1 @@
+Improve actions security documentation

doc/source/vulnerability-actions/index.rst

@@ -55,11 +55,45 @@ Check actions security action
 
    #. Create a virtual environment with ``python -m venv .venv`` and activate it.
    #. Install zizmor: ``pip install zizmor==1.12.1``.
+   #. If the repository doesn't use a custom ``zizmor.yml`` file, download the ``zizmor.yml`` file from the
+      `ansys/action check-actions-security folder <https://github.com/ansys/actions/tree/main/check-actions-security>`_
+      and move it to the root of the repository.
+
+      #. If ``trust-ansys-actions`` has been set to false in the workflow (i.e., you pin ``ansys/actions`` with a SHA instead of a tag), you must edit the
+         default policies in ``zizmor.yml`` as follows:
+
+         .. tab-set::
+
+
+            .. tab-item:: Before
+
+               .. code:: yaml
+
+                  rules:
+                  unpinned-uses:
+                     config:
+                        policies:
+                        ansys/*: ref-pin
+                        actions/*: hash-pin
+
+
+            .. tab-item:: After
+
+               .. code:: yaml
+
+                  rules:
+                  unpinned-uses:
+                     config:
+                        policies:
+                        ansys/*: hash-pin
+                        actions/*: hash-pin
+
    #. Run ``zizmor --persona=pedantic .`` for a minimal audit (action's default) or ``zizmor --persona=auditor`` for a stricter audit.
    #. To generate a summary table locally:
 
-      - Download ``zizmor-summary.py`` from the
-        `ansys/action python utilities folder <https://github.com/ansys/actions/tree/main/python-utils>`_.
+      - Download the ``zizmor-summary.py`` file from the
+        `ansys/action python utilities folder <https://github.com/ansys/actions/tree/main/python-utils>`_ and
+        move it to the root of the repository.
       - Set one of the following environment variables:
 
          - ``HIGH_AUDIT_LEVEL=--persona=pedantic`` for minimal audit.