---
component: provenance-governor
version: "1.7"
slug: provenance-governor/writing-policies
canonical_url: "https://docs.gradle.com/develocity/provenance-governor/1.7/writing-policies/"
title: "Writing Policies"
description: "Guidance for writing custom security and compliance policies."
keywords:
  - "attestation"
  - "supply chain"
  - "configuration"
status: current
---

<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

# Writing Policies

<a id="preamble"></a>

You can define policies to evaluate software packages against your organization’s compliance requirements. Policies are written in declarative YAML and are evaluated against published attestations.

> [!WARNING]
> Policies only evaluate the attestations generated by Develocity Provenance Governor. To cover requirements outside the supported attestation types, contact support.

You write policies as declarative YAML documents, version-controlled and readable, using the familiar Kubernetes CRDs style. See below for policy types, architecture, and example flow.

<a id="policy-architecture-overview"></a>

## Policy Architecture Overview

The system works through layered abstraction:

1.  **Policies** define specific rules (e.g., "must use Java 21")
    
2.  **Labels** categorize policies (e.g., `policy.my-corp.com/gate: build`)
    
3.  **PolicyScanDefinitions** select policies via label selectors
    
4.  **API Calls** execute a scan against a specific package
    
5.  **Results** indicate which policies passed or failed
    

This architecture enables:

*   Reusing policies across multiple scans
    
*   Creating environment-specific policy sets (dev, staging, production)
    
*   Organizing policies by team, compliance requirement, or deployment stage
    
*   Changing enforced policies without modifying individual policy definitions
    

<a id="example-flow"></a>

### Example Flow

```yaml
# 1. Define a policy
apiVersion: policy.gradle.com/v1
kind: BuildTool
metadata:
  name: require-gradle-8
  labels:
    policy.my-corp.com/gate: build
spec:
  description: Require Gradle 8.x
  remediation: Upgrade to Gradle 8
  matchingStrategy: must-match
  buildTools:
    - toolType: gradle
      toolVersions:
        - "8.*"

---
# 2. Define a PolicyScanDefinition that selects policies by label
apiVersion: policy.gradle.com/v1
kind: PolicyScanDefinition
metadata:
  name: build-gate-scan
spec:
  description: Build gate policy scan
  policySelector:
    matchLabels:
      policy.my-corp.com/gate: build

# 3. Execute the scan via API against a package
# 4. Review results to see which policies passed or failed
```

<a id="types-of-policies"></a>

## Types of Policies

 
| Policy Kind | Description |
| --- | --- |
| BuildTool | Enforce specific build tool and version usage |
| JavaToolchains | Control Java toolchain (JDK version/vendor) requirements |
| ResolvedDependenciesRepositories | Restrict dependency resolution sources |
| PackageUrl | Allow or block specific dependencies |
| PublishRepositories | Enforce artifact promotion workflows |
| AttestationsExist | Verify required attestation types exist |
| TrustedPublicKeys | Validate attestation signatures |
| VerificationSummary | Evaluate VSA verification results |

<a id="general-policy-structure"></a>

## General policy structure

All policies share a common structure. Policies are modeled as Kubernetes-style custom resources, with `apiVersion`, `kind`, `metadata`, and `spec` properties.

> [!NOTE]
> Policies are not true Kubernetes resources, but the format makes them recognizable to those familiar with Kubernetes.

The following snippet demonstrates the general structure used by all policies:

**Example: General Policy Structure:**

```
apiVersion: policy.gradle.com/v1
kind: TypeOfPolicy (1)
metadata: (2)
  name: friendly-name (3)
  labels: (4)
    policy.my-corp.com/gate: build
    policy.my-corp.com/owner: DevSecOps
spec:
  description: Human-readable description of the policy. (5)
  remediation: Human-readable remediation steps if the policy is violated. (6)
  matchingStrategy: must-match or none-match (7)
  resultsLabels: (8)
    policy.my-corp.com/cvss: critical|high|medium|low (9)
    policy.my-corp.com/severity: minor|sever|warning
    policy.my-corp.com/dry-run: true
    policy.my-corp.com/severity-level: SEV-1,SEV-2,SEV-3
```

1. The kind property defines the type of policy. This will drive what properties are required in the spec property.
2. The metadata.* properties are similar to traditional Kubernetes metadata information which includes name, labels, annotations.
3. The name property is a unique identifier for the policy.
4. Policies that set metadata.labels can be selected by Policy Scan™ evaluations for inclusion if the label satisfies the selector defined. A policy can be included in multiple Policy Scan evaluations.
5. The spec.description explains in human-readable terms what the policy is attesting to about a software package.
6. The spec.remediation explains in human-readable terms what will be reported back in the Policy Scan and what needs done to the software package to make the package compliant.
7. must-match - must match one of the values on the policy. none-match - must not match any of the values on the policy.
8. The spec.resultsLabels define additional labels applied to scan results. Use these to categorize results by severity, compliance type, or ownership.

> [!NOTE]
> Each kind of policy defines policy-specific properties (under the `spec` object). These properties are covered in the individual sections for each policy.

> [!NOTE]
> You can include multiple policies in a single YAML file by separating them with `---`.

<a id="ResultLabels"></a>

### Result labels

Result labels are useful when policies are evaluated as part of a Policy Scan.

The labels can be used to categorize and filter Policy Scan results based on severity, compliance level, or other criteria relevant to your organization’s governance processes. For example, you might use result labels to indicate the severity of a policy violation (e.g., `critical`, `high`, `medium`, `low`), the type of compliance issue (e.g., `security`, `license`, `quality`), or the team responsible for addressing the issue (e.g., `frontend`, `backend`, `devops`).

For detailed reference on each policy type, see [Policy Types](https://docs.gradle.com/develocity/provenance-governor/1.7/policy-types/).

For information on labeling and evaluating, see [Evaluating Policies](https://docs.gradle.com/develocity/provenance-governor/1.7/evaluating-policies/).