# jenkinsci/tekton-client-plugin architecture

> Architecture diagram of the GitHub repository jenkinsci/tekton-client-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jenkinsci/tekton-client-plugin
- Repository: https://github.com/jenkinsci/tekton-client-plugin

## Overview

##### Project Type and Purpose
- This is a Jenkins plugin (“tekton-client-plugin”) written in Java.
- Purpose: allow Jenkins Pipelines to create, manage, delete, and monitor Tekton Pipeline resources on one or more Kubernetes clusters, with live log streaming and GitHub Checks integration.

##### File‐Structure Analysis
- Standard Maven layout (`pom.xml`, `src/main/java`, `src/main/resources`, `src/test`).
- Under `src/main/java/org/waveywaves/jenkins/plugins/tekton` you have:
- **`client` package**: core Tekton client abstractions (`TektonUtils`, `ToolUtils`, HTTP/REST wrappers).
- **`client/build` subpackages**: classes to build / create (`create/Create*`) and delete Tekton resources.
- **`client/logwatch`**: classes to tail logs (`PipelineRunLogWatch`, `TaskRunLogWatch`).
- **`client/global`**: global configuration (`ClusterConfig`, `TektonGlobalConfiguration`).
- Under `src/main/resources` the matching `.jelly` files define the Jenkins UI forms for each step and the global config screens.
- There are Kubernetes manifests under `src/main/kubernetes` and example Tekton definitions under `src/main/tekton/examples`.
- CI/CD and automation scripts: `.github/workflows`, `Jenkinsfile`, `Dockerfile`, `Makefile`, `deploy.sh`.

##### Key README Insights
- Plugin exposes three main Pipeline steps: `tektonCreateRaw`, `tektonCreateCustomTaskRun`, `tektonDeleteRaw`.
- It maps Jenkins environment variables to Tekton parameters, streams live logs, reports status back via GitHub Checks, supports multi‐cluster.

##### Main Components
a. Jenkins Master
– Plugin itself (loaded as an HPI)
– Global Configuration UI
– Pipeline Step Definitions (Jelly UIs + Java `Step` implementations)
b. Tekton Client Library
– HTTP/REST client to Kubernetes API server
– Builders for Tekton CRDs (Tasks, TaskRuns, Pipelines, PipelineRuns)
– Log‐watchers
c. Kubernetes Clusters (one or many)
– Tekton Pipelines CRDs & controllers
– Namespaces where resources are created
d. External Integrations
– GitHub (Checks API)
– Tekton Catalog (remote resolution)

##### Relationships & Data‐Flow
- Jenkins Pipeline invokes a step (e.g. `tektonCreateRaw`).
- Plugin Step code calls into the Tekton Client Library.
- Client sends REST calls to Kubernetes API server(s), creates or deletes CRDs.
- Tekton controllers in the cluster act on those CRDs and schedule TaskRuns/PipelineRuns.
- LogWatchers subscribe or poll the `Pod` logs and stream back to Jenkins Console.
- Plugin posts GitHub Check status updates if configured.
- Jenkins environment variables flow into the client as Tekton parameters.

##### Architectural Patterns & Principles
- **Separation of Concerns**: UI (Jelly) vs. Step logic vs. Tekton API client.
- **Extension Points**: Jenkins `Step` and `GlobalConfiguration` classes define plugin entry points.
- **Builder Pattern**: building custom TaskRuns programmatically (classes under `build/create`).
- **Adapter/Wrapper**: abstracts away direct Kubernetes client details in `TektonUtils`, `ToolUtils`.
- **Observer/Listener**: log‐watching classes listen for Pod events or logs and push to Jenkins.

##### Technologies & Frameworks
- Java 8+, Jenkins Plugin API (HPI), Jelly for UI
- Maven for build (`pom.xml`), Docker for containerizing tests or deployments
- Kubernetes API (client via `kubectl` or HTTP)
- Tekton CRDs: Task, TaskRun, Pipeline, PipelineRun
- JUnit & MockServer for tests (under `src/test`)
- GitHub Checks API integration

##### Final Advice
- How environment variables map into Tekton parameters (optional annotation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Jenkins Master Plugin Layer
    subgraph "Jenkins Master" 
        direction TB
        subgraph "Global Configuration UI"
            direction TB
            TektonGlobalConfiguration["TektonGlobalConfiguration (Java)"]:::plugin
            TGC_Jelly["config.jelly (UI)"]:::plugin
        end
        subgraph "Cluster Configuration UI"
            direction TB
            ClusterConfig["ClusterConfig (Java)"]:::plugin
            CC_Jelly["config.jelly (UI)"]:::plugin
        end
        subgraph "Pipeline Steps"
            direction TB
            CreateRaw["tektonCreateRaw<br/>(Java)"]:::plugin
            CreateRaw_Jelly["CreateRaw/config.jelly"]:::plugin
            CreateCustom["tektonCreateCustomTaskRun<br/>(Java)"]:::plugin
            CreateCustom_Jelly["CreateCustomTaskrun/config.jelly"]:::plugin
            DeleteRaw["tektonDeleteRaw<br/>(Java)"]:::plugin
            DeleteRaw_Jelly["DeleteRaw/config.jelly"]:::plugin
        end
    end

    %% Tekton Client Library
    subgraph "Tekton Client Library" 
        direction TB
        subgraph "Core Utilities"
            TektonUtils["TektonUtils"]:::plugin
            ToolUtils["ToolUtils"]:::plugin
            LogUtils["LogUtils"]:::plugin
        end
        subgraph "Builder Pattern for CRDs"
            BaseStep["BaseStep"]:::plugin
            CreatePackage["build/create package"]:::plugin
            DeletePackage["build/delete package"]:::plugin
        end
        subgraph "Log Watchers"
            PipelineRunLogWatch["PipelineRunLogWatch"]:::plugin
            TaskRunLogWatch["TaskRunLogWatch"]:::plugin
        end
    end

    %% Kubernetes Clusters
    subgraph "Kubernetes Clusters" 
        direction TB
        APIServer["Kubernetes API Server"]:::k8s
        TektonControllers["Tekton Controllers"]:::k8s
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        GitHubChecks["GitHub Checks API"]:::external
        TektonCatalog["Tekton Catalog"]:::external
    end

    %% Examples, Manifests, CI/CD, Tests
    subgraph "Additional Resources"
        direction TB
        DeploymentManifest["deployment.yaml"]:::k8s
        ExampleYaml["home-is-set.yaml"]:::plugin
        JenkinsfileNode["Jenkinsfile"]:::external
        DockerfileNode["Dockerfile"]:::external
        MakefileNode["Makefile"]:::external
        DeployScript["deploy.sh"]:::external
        GHWorkflows[".github/workflows"]:::external
        TestHarness["Test Harness (src/test)"]:::external
    end

    %% Data Flows
    CreateRaw -->|"invoke"| TektonUtils
    CreateCustom -->|"invoke"| TektonUtils
    DeleteRaw -->|"invoke"| TektonUtils
    TektonUtils -->|"HTTP/REST"| APIServer
    ToolUtils -->|"HTTP/REST"| APIServer
    APIServer -->|"CRUD CRDs"| TektonControllers
    TektonControllers -->|"Pod Logs"| PipelineRunLogWatch
    TektonControllers -->|"Pod Logs"| TaskRunLogWatch
    PipelineRunLogWatch -->|"stream logs"| CreateRaw
    TaskRunLogWatch -->|"stream logs"| CreateRaw
    CreateRaw -->|"env vars→params"| TektonUtils
    CreateRaw -->|"post status"| GitHubChecks
    CreateCustom -->|"post status"| GitHubChecks
    DeleteRaw -->|"post status"| GitHubChecks

    %% Click Events
    click TektonGlobalConfiguration "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/global/TektonGlobalConfiguration.java"
    click TGC_Jelly "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/resources/org/waveywaves/jenkins/plugins/tekton/client/global/TektonGlobalConfiguration/config.jelly"
    click ClusterConfig "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/global/ClusterConfig.java"
    click CC_Jelly "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/resources/org/waveywaves/jenkins/plugins/tekton/client/global/ClusterConfig/config.jelly"
    click CreateRaw "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/build/create/CreateRaw.java"
    click CreateRaw_Jelly "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/resources/org/waveywaves/jenkins/plugins/tekton/client/build/create/CreateRaw/config.jelly"
    click CreateCustom "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/build/create/CreateCustomTaskrun.java"
    click CreateCustom_Jelly "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/resources/org/waveywaves/jenkins/plugins/tekton/client/build/create/CreateCustomTaskrun/config.jelly"
    click DeleteRaw "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/build/delete/DeleteRaw.java"
    click DeleteRaw_Jelly "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/resources/org/waveywaves/jenkins/plugins/tekton/client/build/delete/DeleteRaw/config.jelly"
    click TektonUtils "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/TektonUtils.java"
    click ToolUtils "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/ToolUtils.java"
    click LogUtils "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/LogUtils.java"
    click BaseStep "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/build/BaseStep.java"
    click CreatePackage "https://github.com/jenkinsci/tekton-client-plugin/tree/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/build/create"
    click DeletePackage "https://github.com/jenkinsci/tekton-client-plugin/tree/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/build/delete"
    click PipelineRunLogWatch "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/logwatch/PipelineRunLogWatch.java"
    click TaskRunLogWatch "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/java/org/waveywaves/jenkins/plugins/tekton/client/logwatch/TaskRunLogWatch.java"
    click DeploymentManifest "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/kubernetes/deployment.yaml"
    click ExampleYaml "https://github.com/jenkinsci/tekton-client-plugin/blob/master/src/main/tekton/examples/v1beta1/taskruns/home-is-set.yaml"
    click JenkinsfileNode "https://github.com/jenkinsci/tekton-client-plugin/tree/master/Jenkinsfile"
    click DockerfileNode "https://github.com/jenkinsci/tekton-client-plugin/tree/master/Dockerfile"
    click MakefileNode "https://github.com/jenkinsci/tekton-client-plugin/tree/master/Makefile"
    click DeployScript "https://github.com/jenkinsci/tekton-client-plugin/blob/master/deploy.sh"
    click GHWorkflows "https://github.com/jenkinsci/tekton-client-plugin/tree/master/.github/workflows"
    click TestHarness "https://github.com/jenkinsci/tekton-client-plugin/tree/master/src/test/java/org/waveywaves/jenkins/plugins/tekton/client"

    %% Styles
    classDef plugin fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef k8s fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef external fill:#c8e6c9,stroke:#43a047,color:#1b5e20
```
