From 3c548d5ffbbc4b39fd5c818d5c2b1b271770fe9b Mon Sep 17 00:00:00 2001
From: "Jose I. Paris" <jiparis@chainloop.dev>
Date: Wed, 6 Nov 2024 20:14:22 +0100
Subject: [PATCH] feat(docs): document policy groups (#1489)

Signed-off-by: Jose I. Paris <jiparis@chainloop.dev>
---
 docs/docs/reference/policies.mdx | 66 ++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/docs/docs/reference/policies.mdx b/docs/docs/reference/policies.mdx
index e7fa1cfdb..57d152a76 100644
--- a/docs/docs/reference/policies.mdx
+++ b/docs/docs/reference/policies.mdx
@@ -195,3 +195,69 @@ For example
 
 ## How to write a Chainloop policy in Rego
 Check [this how-to](/guides/rego-policies) to know how you can write Chainloop policies in [Rego language](https://www.openpolicyagent.org/docs/latest/policy-language/#learning-rego).
+
+
+## Policy Groups
+
+This feature allow operators to group related policies into one single entity that can be reused across the organization.
+With Policy Groups, materials and policies can be enforced in Chainloop contracts with little or no effort.
+
+For example, they might want to create a "SBOM quality" group with some SBOM-related policies. The policy groups can be defined this way:
+```yaml
+# sbom-quality.yaml
+apiVersion: workflowcontract.chainloop.dev/v1
+kind: PolicyGroup
+metadata:
+  name: sbom-quality
+  description: This policy group applies a number of SBOM-related policies
+  annotations:
+    category: SBOM
+spec:
+  inputs:
+    - name: bannedLicenses
+      description: comma separated list of licenses to ban
+      required: true
+    - name: bannedComponents
+      description: comma separated list of components to ban
+      required: true
+  policies:
+    materials:
+      - name: sbom
+        type: SBOM_CYCLONEDX_JSON
+        policies:
+        - ref: sbom-banned-licenses
+          with:
+            licenses: {{ inputs.bannedLicenses }}
+        - ref: sbom-banned-components
+          with:
+            components: {{ inputs.bannedComponents }}
+```
+
+### Using Policy Groups
+
+This policy group could be applied to any contract:
+```yaml
+schemaVersion: v1
+materials: []
+policyGroups:
+  - ref: file://groups/sbom-quality-group.yaml
+    with:
+      bannedComponents: log4j@2.14.1
+      bannedLicenses: AGPL-1.0-only, AGPL-1.0-or-later, AGPL-3.0-only, AGPL-3.0-or-later
+```
+
+As we introduced earlier, policy groups define both materials and policies applied to them. Once they are included to a contract,
+they become part of the contract. From this point of view, they can be seen as subcontracts.
+
+### Policy group parameters
+
+In the same way as [policies](policies#policy-arguments), groups can accept arguments, which are specified in the `inputs` section.
+Then those inputs can be passed down to policies using interpolation.
+
+In the example above, `bannedComponents` input parameter (which is mandatory) is passed to the underlying policy with the expression `{{ inputs.banneComponents }}`
+```yaml
+        - ref: sbom-banned-components
+          with:
+            components: {{ inputs.bannedComponents }}
+```
+