Skip to content

Commit e0ef93b

Browse files
committed
refactoring and expanding
1 parent 60db14d commit e0ef93b

File tree

2 files changed

+50
-22
lines changed

2 files changed

+50
-22
lines changed

src/doc/en/developer/github.rst

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -73,32 +73,17 @@ and check::
7373

7474
which will show the default repo along with its readme, which is quite long.
7575

76-
Framework for testing GitHub Actions locally
77-
--------------------------------------------
76+
``gh`` extensions
77+
-----------------
7878

79-
A useful extension to ``gh`` allows testing of Sage's GitHub Actions locally,
80-
using Docker. It is called ``act`` and can be installed as a ``gh extension``::
79+
``gh`` is extendable; e.g. a useful extension to ``gh`` allows testing of
80+
Sage's GitHub Actions locally, using Docker. It is called ``act`` and can be
81+
installed by running
8182

8283
[alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act
8384

84-
Extra steps needed for configuration of Docker to run Actions locally can be found on
85-
`act's GitHub <https://github.com/nektos/act>`_
86-
87-
After it's set up, one can e.g. list all the available actions::
88-
89-
[alice@localhost sage]$ gh act -l
90-
Stage Job ID Job name Workflow name Workflow file Events
91-
0 build build Build & Test build.yml workflow_dispatch,pull_request,push
92-
0 test Conda Build & Test using Conda ci-conda.yml push,pull_request,workflow_dispatch
93-
0 cygwin-stage-i-b cygwin-stage-i-b CI cygwin-standard ci-cygwin-standard.yml push,workflow_dispatch
94-
[...]
95-
96-
run a particular action ``foobar`` ::
97-
98-
[alice@localhost sage]$ gh act -j foobar
99-
...
100-
101-
and so on.
85+
Append `--force` flag to force an upgrade.
86+
More details on configuring and using `gh act` are in :ref:`chapter-portability_testing`.
10287

10388

10489
Linking Git to your GitHub account

src/doc/en/developer/portability_testing.rst

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1152,6 +1152,49 @@ are available:
11521152
ptest`` has not been run yet.
11531153

11541154

1155+
Testing GitHub Actions locally
1156+
==============================
1157+
1158+
`act <https://github.com/nektos/act>`_ is a tool, written in Go, and using Docker,
1159+
to run GitHub Actions locally; in particular, it speeds up developing Actions.
1160+
We recommend using `gh extension` facility to install `act`. ::
1161+
1162+
[alice@localhost sage]$ gh extension install https://github.com/nektos/gh-act
1163+
1164+
Extra steps needed for configuration of Docker to run Actions locally can be found on
1165+
`act's GitHub <https://github.com/nektos/act>`_
1166+
1167+
Here we give a very short sampling of `act`'s capabilities. If you installed standalone
1168+
`act`, it should be called as `act`, not as `gh act`.
1169+
After the set up, one can e.g. list all the available actions::
1170+
1171+
[alice@localhost sage]$ gh act -l
1172+
Stage Job ID Job name Workflow name Workflow file Events
1173+
0 build build Build & Test build.yml workflow_dispatch,pull_request,push
1174+
0 test Conda Build & Test using Conda ci-conda.yml push,pull_request,workflow_dispatch
1175+
0 cygwin-stage-i-b cygwin-stage-i-b CI cygwin-standard ci-cygwin-standard.yml push,workflow_dispatch
1176+
[...]
1177+
1178+
run a particular action ``foobar`` ::
1179+
1180+
[alice@localhost sage]$ gh act -j foobar
1181+
...
1182+
1183+
and so on.
1184+
1185+
By default, `act` pulls all the data needed from the next, but it can also cache it,
1186+
speeding up repeated runs quite a lot. The following repeats running of ``foobar`` using cached data::
1187+
1188+
[alice@localhost sage]$ gh act -p false -v -r -j foobar
1189+
1190+
Here `-p false` means using already pulled Docker images, and `-r` means do not remove Docker images
1191+
after a successful run which used them. This, and many more details, can be found by running `gh act -h`, as well
1192+
as reading `act`'s documentation.
1193+
1194+
.. TODO::
1195+
1196+
Add more Sage-specfic details for using `act`. PRs welcome!
1197+
11551198
Using our pre-built Docker images for development in VS Code
11561199
============================================================
11571200

0 commit comments

Comments
 (0)