user: actions: jobs.<job_id>.strategy.matrix

docs/user/actions.md

@@ -391,6 +391,8 @@ The following are identical to the matching environment variable
 | token             |
 | workspace         |
 
+Example: `${{ github.SHA }}`
+
 The `github.event` object is set to the payload associated with the
 event (`github.event_name`) that triggered the workflow.
 
@@ -400,6 +402,25 @@ event (`github.event_name`) that triggered the workflow.
   - `pull_request_target` from the [same repository](https://codeberg.org/forgejo/docs/src/branch/v1.21/docs/user/actions-contexts/pull-request/root/pull_request_target/github)
   - `pull_request_target` from a [forked repository](https://codeberg.org/forgejo/docs/src/branch/v1.21/docs/user/actions-contexts/pull-request/fork-org/pull_request_target/github)
 
+### matrix
+
+An object that exists in the context of a job where `jobs.<job_id>.strategy.matrix` is defined . For instance:
+
+```yaml
+jobs:
+  actions:
+    runs-on: self-hosted
+    strategy:
+      matrix:
+        info:
+          - version: v1.22
+            branch: next
+```
+
+Example: `${{ matrix.info.version }}`
+
+[Check out the example](https://code.forgejo.org/forgejo/end-to-end/src/commit/b6591e2f71196b12f6e0851774f0bd6e2148ec18/.forgejo/workflows/actions.yml#L22-L37).
+
 ## Workflow reference guide
 
 The syntax and semantics of the YAML file describing a `workflow` are _partially_ explained here. When an entry is missing the [GitHub Actions](https://docs.github.com/en/actions) documentation may be helpful because there are similarities. But there also are significant differences that require testing.
@@ -544,6 +565,44 @@ The `runs-on: lxc` label will run the jobs in a [LXC](https://linuxcontainers.or
 
 The `runs-on: self-hosted` label will run the jobs directly on the host, in a shell spawned from the runner. It provides no isolation at all.
 
+### `jobs.<job_id>.strategy.matrix`
+
+If present, it will generate a matrix from the content of the object
+and create one job per cell in the matrix instead of a single job.
+
+For instance:
+
+```yaml
+jobs:
+  test:
+    runs-on: self-hosted
+    strategy:
+      matrix:
+        variant: ["bookworm", "bullseye"]
+	node: ["18", "20"]
+```
+
+Will create four jobs where:
+
+- `matrix.variant` = "bookworm" & `matrix.node` = "18"
+- `matrix.variant` = "bookworm" & `matrix.node` = "20"
+- `matrix.variant` = "bullseye" & `matrix.node` = "18"
+- `matrix.variant` = "bullseye" & `matrix.node` = "20"
+
+They each run independently and can use the `matrix` context to access these values. For instance:
+
+```yaml
+jobs:
+  test:
+---
+steps:
+  - uses: https://code.forgejo.org/actions/setup-node@v4
+    with:
+      node-version: '${{ matrix.node }}'
+```
+
+[Check out the example](https://code.forgejo.org/forgejo/end-to-end/src/commit/b6591e2f71196b12f6e0851774f0bd6e2148ec18/.forgejo/workflows/actions.yml#L22-L37).
+
 ### `jobs.<job_id>.container`
 
 - **Docker or Podman:**