VerificationPolicy

API reference for the VerificationPolicy v1alpha1 resource

VerificationPolicy is at v1alpha1 stability level and subject to change.

A VerificationPolicy defines rules for verifying the authenticity and integrity of Tekton resources using cryptographic signatures.

Resource Definition

apiVersion · string · required

tekton.dev/v1alpha1

kind · string · required

VerificationPolicy

metadata · ObjectMeta · required

Standard Kubernetes metadata.

spec · VerificationPolicySpec · required

Specification of the verification policy.

VerificationPolicySpec

resources · []ResourcePattern · required

Patterns defining which resources this policy applies to.

Show ResourcePattern fields

pattern · string · required

Regex pattern to match resource sources.

Examples:

• https://github.com/tektoncd/catalog.git
• https://github.com/tektoncd/*
• gcr.io/tekton-releases/catalog/upstream/*
• https://artifacthub.io/*

authorities · []Authority · required

List of authorities (public keys) for validating signatures.

Show Authority fields

name · string · required

Name of this authority.

key · KeyRef

Public key reference for validation.

Show KeyRef fields

data · string

Inline public key data (PEM format).

secretRef · SecretReference

Reference to a Secret containing the public key.

Show SecretReference fields

name · string

Name of the secret.

namespace · string

Namespace of the secret.

kms · string

KMS URL for the public key (not yet supported).

Example format:

gcpkms://projects/[PROJECT]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY]/cryptoKeyVersions/[VERSION]

hashAlgorithm · string · default: "sha256"

Hash algorithm for signature verification.

Supported values:

• sha224
• sha256 (default)
• sha384
• sha512

mode · string · default: "enforce"

How to handle verification failures.

Values:

• enforce - Fail the TaskRun/PipelineRun if verification fails (default)
• warn - Log warnings but don’t fail on verification failure

How Verification Works

1. When a Task or Pipeline is fetched via remote resolution, Tekton checks for matching VerificationPolicies
2. The resource URL is matched against the resources patterns
3. If a policy matches, the resource’s signature is verified using the specified authorities
4. Verification uses the configured hash algorithm and public key
5. Based on the mode, verification failure either blocks execution or logs a warning

Signature Format

Tekton uses Sigstore/cosign compatible signatures. Resources should be signed using cosign or compatible tools.

Example: Verify GitHub Resources

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verify-tekton-catalog
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: tekton-catalog-key
      key:
        data: |
          -----BEGIN PUBLIC KEY-----
          MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
          -----END PUBLIC KEY-----
        hashAlgorithm: sha256
  mode: enforce

Example: Verify OCI Bundles

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verify-gcr-bundles
spec:
  resources:
    - pattern: "gcr.io/tekton-releases/catalog/upstream/*"
  authorities:
    - name: gcr-key
      key:
        secretRef:
          name: cosign-pub-key
          namespace: tekton-pipelines
  mode: enforce

Example: Warn Mode

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verify-external-resources
spec:
  resources:
    - pattern: "https://github.com/external-org/*"
  authorities:
    - name: external-key
      key:
        data: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----
  mode: warn

In warn mode, verification failures are logged but don’t prevent execution, useful for gradual policy rollout.