Feature: Tekton Pipelines-as-Code Forwarding Support

[waveywaves]

Background

The tekton-client-plugin should support integration with Tekton Pipelines-as-Code (PaC) to allow Jenkins to act as a proxy/bridge for PaC events and triggers. This would enable Jenkins to sit in front of PaC and forward webhook events or trigger pipeline runs in clusters where direct access from external providers (GitHub, GitLab, etc.) may be restricted.

Problem Statement

Currently, there's no built-in way for Jenkins to integrate with Tekton Pipelines-as-Code, which limits the ability to:

• Handle webhook events from external Git providers when clusters are not directly accessible
• Provide a centralized point for managing PaC triggers through Jenkins
• Leverage Jenkins' authentication and authorization features for PaC operations
• Bridge network gaps between external providers and internal Kubernetes clusters

Proposed Solution

Implement two integration patterns to support different use cases and network topologies:

Pattern A: Transparent Webhook Reverse-Proxy (Full PaC Features)

• Preserve native PaC provider model (GitHub App/GitLab/Bitbucket)
• Jenkins acts as a transparent proxy, forwarding webhooks verbatim to PaC controller
• Maintains all PaC features (PR checks, /retest, /ok-to-test, annotations, etc.)

Pattern B: Trigger-Only via PaC "Incoming Webhook" (Simple, Firewall-Friendly)

• Jenkins calls PaC's /incoming endpoint with shared secrets
• Works even when external providers cannot reach the cluster directly
• Simpler implementation but with limited PaC features (comment-based status vs Checks)

Requirements

Core Components to Implement

1. PaC Bridge Module

   • Global configuration for Kubernetes connection and PaC controller URL
   • Auto-detection of PaC controller URL from ConfigMap/OpenShift Route
   • Repository mapping UI for managing Repository CRs and Secrets

2. Webhook Reverse-Proxy Endpoint (Pattern A)

   • Stapler endpoint at /tekton/pac/webhook
   • HMAC signature verification (e.g., GitHub X-Hub-Signature-256)
   • Verbatim payload forwarding without body mutation
   • Support for GitHub Apps, GitLab, and Bitbucket webhooks

3. Incoming Trigger Endpoint & Pipeline Step (Pattern B)

   • REST endpoint at /tekton/pac/incoming
   • Pipeline step pacTrigger(...) for programmatic triggering
   • Support for dynamic parameters (PR numbers, branch names, etc.)

4. Repository Management

   • UI for creating/patching Repository CRDs in target namespaces
   • Secret management for provider tokens and webhook secrets
   • Integration with Fabric8 Kubernetes client for CRD operations

Optional Enhancements

5. Status Mirroring

   • For Pattern B: Mirror PipelineRun status to GitHub Checks
   • Integration with Jenkins GitHub Checks plugin
   • Link back to OpenShift Console/Tekton Dashboard

6. Enhanced UX

   • Live log streaming from TaskRuns in Jenkins builds
   • Links to external console URLs
   • Display PR annotations and log snippets from PaC

Implementation Details

API Endpoints

// Pattern A: Webhook proxy
@WebMethod(name = "webhook")
public HttpResponse doWebhook(StaplerRequest req, StaplerResponse rsp) {
    // Verify HMAC signature
    // Forward payload verbatim to PaC controller
}

// Pattern B: Incoming trigger
@WebMethod(name = "incoming") 
public HttpResponse doIncoming(StaplerRequest req, StaplerResponse rsp) {
    // Construct JSON payload for PaC /incoming endpoint
    // Execute POST to PaC controller
}

Configuration Objects

• PaCGlobalConfiguration - Global settings for PaC integration
• PaCRepository - Per-repository configuration mapping
• PaCCredentials - Secure credential storage for tokens/secrets

Security Considerations

• Signature Verification: Validate HMAC signatures before forwarding
• Multi-tenancy: Ensure Repository CRs are properly scoped to namespaces
• Credential Management: Secure storage of provider tokens and webhook secrets
• Body Integrity: Preserve exact webhook payloads to maintain signature validity

Acceptance Criteria

Phase 1: Basic Implementation

• PaC controller URL auto-detection from cluster
• Repository CR management UI
• Pattern B implementation (incoming webhook trigger)
• Basic pipeline step for triggering PaC runs
• Documentation and examples

Phase 2: Advanced Features

• Pattern A implementation (transparent webhook proxy)
• HMAC signature verification for major Git providers
• Support for GitHub Apps, GitLab, and Bitbucket webhooks
• Enhanced error handling and logging

Phase 3: Polish & Integration

• Status mirroring to GitHub Checks (optional)
• Live log streaming integration
• Links to external dashboards
• Comprehensive test coverage
• Performance optimization

Technical Notes

Dependencies

• Fabric8 Kubernetes Client for CRD operations
• Apache HttpClient for webhook forwarding
• Jenkins GitHub Checks plugin (for status mirroring)
• Existing tekton-client-plugin infrastructure

CRD Integration

The implementation will need to work with PaC's repositories.pipelinesascode.tekton.dev CRD and handle:

• Repository CR lifecycle management
• Secret creation and management
• Namespace-scoped resource operations
• Validation webhook constraints

Backward Compatibility

This feature should be implemented as an optional module that doesn't affect existing tekton-client-plugin functionality.

Related Links

• Tekton Pipelines-as-Code Documentation
• Jenkins tekton-client-plugin Repository
• GitHub Webhook Security