feat: loop over a matrix (#1767)

website/docs/usage.mdx

@@ -1297,9 +1297,9 @@ tasks:
 
 ## Looping over values
 
-As of v3.28.0, Task allows you to loop over certain values and execute a command
-for each. There are a number of ways to do this depending on the type of value
-you want to loop over.
+Task allows you to loop over certain values and execute a command for each.
+There are a number of ways to do this depending on the type of value you want to
+loop over.
 
 ### Looping over a static list
 
@@ -1316,6 +1316,37 @@ tasks:
         cmd: cat {{ .ITEM }}
 ```
 
+### Looping over a matrix
+
+If you need to loop over all permutations of multiple lists, you can use the
+`matrix` property. This should be familiar to anyone who has used a matrix in a
+CI/CD pipeline.
+
+```yaml
+version: '3'
+
+tasks:
+  default:
+    silent: true
+    cmds:
+      - for:
+          matrix:
+            OS: ["windows", "linux", "darwin"]
+            ARCH: ["amd64", "arm64"]
+        cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
+```
+
+This will output:
+
+```txt
+windows/amd64
+windows/arm64
+linux/amd64
+linux/arm64
+darwin/amd64
+darwin/arm64
+```
+
 ### Looping over your task's sources
 
 You are also able to loop over the sources of your task:

website/static/schema.json

@@ -431,6 +431,9 @@
         },
         {
           "$ref": "#/definitions/for_var"
+        },
+        {
+          "$ref": "#/definitions/for_matrix"
         }
       ]
     },
@@ -467,6 +470,12 @@
       "additionalProperties": false,
       "required": ["var"]
     },
+    "for_matrix": {
+      "description": "A matrix of values to iterate over",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["matrix"]
+    },
     "precondition": {
       "anyOf": [
         {