#Use Harbor Event Triggers

#Overview

Harbor Event Triggers allows you to automatically trigger Tekton pipelines through Harbor's Webhook events. It supports multiple event types, including artifact push, pull, delete, and scanning completion, enabling you to build a complete CI/CD automation workflow for container images and OCI charts.

#Core Features

• Multi-event Type Support: Supports various Harbor events such as Push Artifact, Pull Artifact, Delete Artifact, and Scanning Completed.
• Standardized Trigger Binding: Provides standardized ClusterTriggerBindings to ensure consistency across platforms.
• Flexible Parameter Mapping: Automatically extracts key information from Harbor events for pipeline parameters.
• Multi-artifact Type Support: Supports both container images and OCI charts.

#Supported Event Types

#Basic Event Information

All output variables can be used for pipeline parameter mapping. You can access parameter values using $(tt.params.<param name>).

#Basic Variables (Common to All Events)

#1. Push Artifact Event

Triggered when an artifact (container image or OCI chart) is pushed to a Harbor repository. Suitable for:

• Automated image builds and deployments
• Image validation and testing
• Automated tagging and versioning
• Multi-stage build pipelines

#Push Artifact Event Variables

All basic variables listed above are also available.

#2. Pull Artifact Event

Triggered when an artifact is pulled from a Harbor repository. Suitable for:

• Usage tracking and analytics
• Security monitoring
• Resource consumption tracking
• Deployment verification

#Pull Artifact Event Variables

All basic variables listed above are also available.

#3. Delete Artifact Event

Triggered when an artifact is deleted from a Harbor repository. Suitable for:

• Cleanup automation
• Audit logging
• Resource management
• Compliance tracking

#Delete Artifact Event Variables

All basic variables listed above are available. Note that repository-date-created is not available for delete events.

#4. Scanning Completed Event

Triggered when a vulnerability scan of an artifact is completed. Suitable for:

• Security policy enforcement
• Automated security checks
• Vulnerability reporting
• Automated remediation workflows

#Scanning Completed Event Variables

All basic variables listed above are available. Note that repository-date-created is not available for scanning events.

#Configuration Guide

#Handling Optional Fields

Some fields in Harbor events may be optional or missing depending on the event type or how the artifact is referenced. For example:

• artifact-tag: May be missing if the artifact is referenced by digest only
• repository-date-created: Available in push and pull events, but not in delete and scanning events

Important: When using ClusterTriggerBindings that reference optional fields, you must provide default values in your TriggerTemplate for those parameters. If a field is missing from the payload and no default is provided, the trigger will fail with a JSONPath parsing error.

Example: To handle an optional artifact-tag field, configure your TriggerTemplate like this:

spec:
  params:
    - name: artifact-tag
      default: ""  # Empty string default for optional field

This ensures that if the tag field is missing from the Harbor event payload, the trigger will use an empty string instead of failing.

#Prerequisites

1. An EventListener has been created in the environment and is capable of processing Trigger in the target namespace. Please contact your platform administrator for more information.
2. Harbor can access the EventListener mentioned above.
3. The required Pipeline, as well as the necessary running configurations, have been created.
4. You have permissions to modify the Webhook settings of the Harbor project.

#Configure Webhook via Harbor UI

1. Visit your Harbor project settings.
2. Navigate to Webhooks.
3. Click New Webhook.
4. Configure the webhook:
   • Name: Enter a descriptive name (e.g., tekton-webhook)
   • Endpoint URL: Enter the EventListener URL, for example:

     http://<your-eventlistener-url>
     or

     https://<your-eventlistener-url>
   • Auth Header: (Optional) Configure authentication header if required.
   • Skip Certificate Verification: Enable if using self-signed certificates.
5. Select the event types as needed:
   • Push Artifact: Triggered when artifacts are pushed
   • Pull Artifact: Triggered when artifacts are pulled
   • Delete Artifact: Triggered when artifacts are deleted
   • Scanning Completed: Triggered when vulnerability scanning is completed
6. Click Save.

#Pipeline Trigger Configuration Example

If the goal is to implement continuous integration through the trigger with the following requirements:

• Automatically trigger automated build and deployment when an image is pushed.
• Automatically trigger security checks when scanning is completed.

To simplify this documentation, we assume the pipeline is ready with the following parameters provided:

Next, we only need to configure the two triggers below:

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
    name: my-pipeline-push   # It is suggested to modify the prefix based on the pipeline name
    namespace: my-namespace  # Change to actual namespace
spec:
    bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-push-artifact
    interceptors: # Filter to only process PUSH_ARTIFACT events
    - ref:
        kind: ClusterInterceptor
        name: cel
      params:
      - name: filter
        value: body.type == "PUSH_ARTIFACT"  # Only trigger on push events
    template:
      spec:
        params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # Optional field: may be empty if artifact is referenced by digest only
        - name: artifact-digest
        resourcetemplates:
        - apiVersion: tekton.dev/v1
          kind: PipelineRun
          metadata:
              generateName: my-pipeline-push- # It is suggested to modify the prefix based on the pipeline name
          spec:
              pipelineRef:
                name: my-pipeline  # Change to actual pipeline name
              params:
              - name: repository-full-name
                value: $(tt.params.repository-full-name)
              - name: artifact-tag
                value: $(tt.params.artifact-tag)
              - name: artifact-digest
                value: $(tt.params.artifact-digest)
              workspaces: # Workspaces need to be modified based on pipeline requirements and environment configuration
              - name: output
                emptyDir: {}

kubectl apply -f harbor-push-trigger.yaml

interceptors:
- ref:
    kind: ClusterInterceptor
    name: cel
  params:
  - name: filter
    value: body.type == "PUSH_ARTIFACT"

interceptors:
- ref:
    kind: ClusterInterceptor
    name: cel
  params:
  - name: filter
    value: body.type == "PULL_ARTIFACT"

apiVersion: triggers.tekton.dev/v1beta1
kind: Trigger
metadata:
  name: my-pipeline-scanning # It is suggested to modify the prefix based on the pipeline name
  namespace: my-namespace # Change to actual namespace
spec:
  bindings:
    - ref:
        kind: ClusterTriggerBinding
        name: harbor-scanning-completed
  interceptors: # Add Interceptor to filter successful scans only, or filter by vulnerability severity
  - ref:
      kind: ClusterInterceptor
      name: cel
    params:
    - name: filter
      value: |
        # Filter for successful scans only
        # Note: scan_overview structure varies by scan type, adjust the path accordingly
        # For vulnerability scans, the structure is: body.event_data.resources[0].scan_overview["application/vnd.security.vulnerability.report; version=1.1"].scan_status == "Success"
  template:
    spec:
      params:
        - name: repository-full-name
        - name: artifact-tag
          default: ""  # Optional field: may be empty if artifact is referenced by digest only
        - name: artifact-digest
      resourcetemplates:
      - apiVersion: tekton.dev/v1
        kind: PipelineRun
        metadata:
          generateName: my-pipeline-scan- # It is suggested to modify the prefix based on the pipeline name
        spec:
          pipelineRef:
            name: my-pipeline # Modify based on the pipeline name
          params:
            - name: repository-full-name
              value: $(tt.params.repository-full-name)
            - name: artifact-tag
              value: $(tt.params.artifact-tag)
            - name: artifact-digest
              value: $(tt.params.artifact-digest)
          workspaces: # Workspaces need to be modified based on pipeline requirements and environment configuration
            - name: output
              emptyDir: {}

kubectl apply -f harbor-scanning-trigger.yaml

#Use Cases

#Use Case 1: Automated Image Deployment

Scenario: Automatically deploy container images to staging or production environments when they are pushed to Harbor.

Configuration:

• Create a Trigger using harbor-push-artifact binding
• Configure the pipeline to pull the image using artifact-resource-url and deploy it to the target environment
• Optionally filter by repository namespace or tag pattern using CEL interceptors

Example Use Cases:

• Deploy images tagged with production to production environment
• Deploy images from specific namespaces to staging environment
• Trigger deployment only for images matching certain naming patterns

#Use Case 2: Security Policy Enforcement

Scenario: Enforce security policies by blocking deployments of images with critical vulnerabilities.

Configuration:

• Create a Trigger using harbor-scanning-completed binding
• Use CEL interceptor to filter scans with critical vulnerabilities
• Configure the pipeline to:
  • Check vulnerability counts from scan results
  • Block deployment if critical vulnerabilities exceed threshold
  • Send notifications to security team

Example Use Cases:

• Prevent deployment of images with critical vulnerabilities
• Automatically quarantine images with high-risk vulnerabilities
• Generate security reports for compliance

#Use Case 3: Artifact Lifecycle Management

Scenario: Automatically manage artifact lifecycle based on usage patterns and retention policies.

Configuration:

• Create Triggers for harbor-pull-artifact and harbor-delete-artifact events
• Track artifact usage and age
• Automatically delete old or unused artifacts based on policies

Example Use Cases:

• Archive old artifacts that haven't been pulled in 90 days
• Clean up development artifacts after deployment to production
• Maintain compliance with data retention policies

#Use Case 4: Multi-Stage CI/CD Pipeline

Scenario: Build a complete CI/CD pipeline that triggers on image push, runs tests, performs security scans, and deploys based on scan results.

Configuration:

• Create multiple Triggers:
  1. harbor-push-artifact trigger: Start build and test pipeline
  2. harbor-scanning-completed trigger: Continue to deployment if scan passes
• Use pipeline dependencies and workspaces to share artifacts between stages

Example Use Cases:

• Build → Test → Scan → Deploy workflow
• Parallel testing and scanning for faster feedback
• Conditional deployment based on test and scan results