Writing Policies

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.

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.

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

Example Flow

# 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

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

General policy structure

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

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 The spec.matchingStrategy defines how the policy values are evaluated against the attestation data:

  • 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.
Each kind of policy defines policy-specific properties (under the spec object). These properties are covered in the individual sections for each policy.
You can include multiple policies in a single YAML file by separating them with ---.

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.

For information on labeling and evaluating, see Evaluating Policies.