gh-36117: run GitHub actions locally using gh act
    
document how to run GitHub actions locally using `gh` and `docker`

`gh` has an extension called `act`, which allows to run Actions locally
(subject to the usual Docker restrictions, e.g. no macOS on Linux)

Still it's very useful, e.g. for debugging purposes.
    
URL: #36117
Reported by: Dima Pasechnik
Reviewer(s): Dima Pasechnik, Kwankyu Lee, Matthias Köppe, Tobias Diez

Author: Release Manager

src/doc/en/developer/github.rst

@@ -73,6 +73,18 @@ and check::
 
 which will show the default repo along with its readme, which is quite long.
 
+``gh`` extensions
+-----------------
+
+``gh`` is extendable; e.g.  a useful extension to ``gh`` allows testing of
+Sage's GitHub Actions locally, using Docker. It is called ``act`` and can be
+installed by running::
+
+    [alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act
+
+Append ``--force`` flag to the command above to force an upgrade of the extension.
+More details on configuring and using ``gh act`` are in :ref:`chapter-portability_testing`.
+
 
 Linking Git to your GitHub account
 ==================================

src/doc/en/developer/portability_testing.rst

@@ -1152,6 +1152,58 @@ are available:
    ptest`` has not been run yet.
 
 
+Testing GitHub Actions locally
+==============================
+
+`act <https://github.com/nektos/act>`_ is a tool, written in Go, and using Docker,
+to run GitHub Actions locally; in particular, it speeds up developing Actions.
+We recommend using ``gh extension`` facility to install ``act``. ::
+
+    [alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act
+
+Extra steps needed for configuration of Docker to run Actions locally can be found on
+`act's GitHub <https://github.com/nektos/act>`_
+
+Here we give a very short sampling of ``act``'s capabilities. If you installed standalone
+``act``, it should be invoked as ``act``, not as ``gh act``.
+After the set up, one can e.g. list all the available linting actions::
+
+    [alice@localhost sage]$ gh act -l | grep lint
+    0      lint-pycodestyle        Code style check with pycodestyle                          Lint                                               lint.yml                push,pull_request
+    0      lint-relint             Code style check with relint                               Lint                                               lint.yml                push,pull_request
+    0      lint-rst                Validate docstring markup as RST                           Lint                                               lint.yml                push,pull_request
+    [alice@localhost sage]$
+
+run a particular action ``lint-rst`` ::
+
+    [alice@localhost sage]$ gh act -j lint-rst
+    ...
+
+and so on.
+
+By default, ``act`` pulls all the data needed from the next, but it can also cache it,
+speeding up repeated runs quite a lot. The following repeats running of ``lint-rst`` using cached data::
+
+    [alice@localhost sage]$ gh act -p false -r -j lint-rst
+    [Lint/Validate docstring markup as RST]   Start image=catthehacker/ubuntu:act-latest
+    ...
+    | rst: commands[0] /home/alice/work/software/sage/src> flake8 --select=RST
+    |   rst: OK (472.60=setup[0.09]+cmd[472.51] seconds)
+    |   congratulations :) (474.10 seconds)
+    ...
+    [Lint/Validate docstring markup as RST]     Success - Main Lint using tox -e rst
+    [Lint/Validate docstring markup as RST]  Run Post Set up Python
+    [Lint/Validate docstring markup as RST]     docker exec cmd=[node /var/run/act/actions/actions-setup-python@v4/dist/cache-save/index.js] user= workdir=
+    [Lint/Validate docstring markup as RST]     Success - Post Set up Python
+    [Lint/Validate docstring markup as RST]   Job succeeded
+
+Here ``-p false`` means using already pulled Docker images, and ``-r`` means do not remove Docker images
+after a successful run which used them. This, and many more details, can be found by running ``gh act -h``, as well
+as reading ``act``'s documentation.
+
+.. This sectuion is a stub. 
+   More Sage-specfic details for using ``act`` should be added. PRs welcome!
+
 Using our pre-built Docker images for development in VS Code
 ============================================================