# Jenkins Tekton Plugin - Feature Documentation

The Jenkins Tekton Plugin enables Jenkins to interact with Tekton Pipelines running on Kubernetes clusters. It provides build steps for creating, managing, and monitoring Tekton resources directly from Jenkins pipelines.

## Part 1: Tekton Resource Creation

### 1. Raw Resource Creation (`CreateRaw` class)

#### Core Creation Functions:

**`createTask(InputStream inputStream): String`**
- Loads Task from input stream using taskClient
- Sets namespace if provided and not already specified in resource
- Creates Task in specified or default namespace
- Returns: Resource name of created Task

**`createTaskRun(InputStream inputStream): String`**
- Loads TaskRun from input stream using taskRunClient
- Sets namespace if provided and not already specified in resource
- Creates TaskRun in specified or default namespace
- Calls `streamTaskRunLogsToConsole()` for real-time log monitoring
- Returns: Resource name of created TaskRun
- Throws: Exception if TaskRun execution fails

**`createPipeline(InputStream inputStream): String`**
- Loads Pipeline from input stream using pipelineClient
- Sets namespace if provided and not already specified in resource
- Creates Pipeline in specified or default namespace
- Returns: Resource name of created Pipeline

**`createPipelineRun(InputStream inputStream, EnvVars envVars): String`**
- Loads PipelineRun from input stream using pipelineRunClient
- Sets namespace if provided and not already specified in resource
- Calls `enhancePipelineRunWithEnvVars()` to inject Jenkins environment variables
- Creates PipelineRun and publishes GitHub-style checks status
- Calls `streamPipelineRunLogsToConsole()` for real-time log monitoring
- Reloads PipelineRun to check final status conditions
- Returns: Resource name of created PipelineRun
- Throws: Exception if PipelineRun has failed status condition

**`createWithResourceSpecificClient(TektonResourceType resourceType, InputStream inputStream, EnvVars envVars): String`**
- Router method that delegates to specific creation functions based on resource type
- Switch statement handles: task, taskrun, pipeline, pipelinerun
- Returns: Result from specific creation function
- Throws: Exception from underlying creation methods

#### Input Processing Functions:

**`runCreate(Run<?, ?> run, FilePath workspace, EnvVars envVars): String`**
- Main orchestration method for resource creation
- Handles input type processing (URL, YAML, FILE)
- Downloads data from URL or reads from file/YAML content
- Calls `convertTektonData()` for catalog processing if enabled
- Uses `getKindFromInputStream()` to detect resource type
- Delegates to `createWithResourceSpecificClient()`
- Handles error reporting and build status setting
- Publishes GitHub checks for PipelineRuns
- Returns: Name of created resource

**`convertTektonData(FilePath workspace, EnvVars envVars, File inputFile, byte[] data): byte[]`**
- Processes Tekton resources for catalog integration
- Handles remote workspace file copying
- Calls `processTektonCatalog()` if enableCatalog is true
- Returns: Processed YAML data as byte array
- Throws: Exception if catalog processing fails

**`processTektonCatalog(EnvVars envVars, File dir, File file, byte[] data): byte[]`**
- Executes jx-pipeline-effective binary to resolve `uses:` syntax
- Creates temporary input/output files
- Builds ProcessBuilder with environment variables
- Executes binary and captures exit code
- Logs process output using `LogUtils.logStream()`
- Returns: Processed YAML data with resolved external references
- Throws: Exception if binary execution fails (exit code != 0)

#### Environment Variable Functions:

**`enhancePipelineRunWithEnvVars(PipelineRun pr, EnvVars envVars): void`**
- Maps Jenkins environment variables to PipelineRun parameters
- Mappings:
- `BUILD_ID` → `BUILD_ID`
- `JOB_NAME` → `JOB_NAME`
- `GIT_COMMIT` → `PULL_PULL_SHA`
- `GIT_BRANCH` → `PULL_BASE_REF` (extracts branch name from refs/origin/branch)
- `GIT_URL` → `REPO_URL`, `REPO_OWNER`, `REPO_NAME`
- Calls `setParamOnPipelineRunSpec()` for each parameter

**`setParamOnPipelineRunSpec(PipelineRunSpec spec, String paramName, String paramValue): void`**
- Sets or updates parameter on PipelineRunSpec
- Creates params list if it doesn't exist
- Updates existing parameter or adds new one
- Handles null values by setting empty string

**`removeGitSuffix(String part): String`**
- Removes `.git` suffix from repository names
- Used when parsing `GIT_URL` for `REPO_NAME` parameter

#### Log Streaming Functions:

**`streamTaskRunLogsToConsole(TaskRun taskRun): void`**
- Creates TaskRunLogWatch instance
- Starts new thread for log watching
- Waits for thread completion using `join()`
- Propagates exceptions from log watch thread
- Throws: Exception if log streaming fails

**`streamPipelineRunLogsToConsole(PipelineRun pipelineRun): void`**
- Creates PipelineRunLogWatch instance
- Starts new thread for log watching
- Waits for thread completion using `join()`
- Propagates exceptions from log watch thread
- Throws: Exception if log streaming fails

### 2. Custom TaskRun Creation (`CreateCustomTaskrun` class)

#### Creation Functions:

**`runCreate(): void`**
- Main creation method for custom TaskRun
- Creates ObjectMeta with name, namespace, generateName
- Creates TaskRef pointing to specified task
- Builds TaskRunSpec with taskRef, workspaces, and params
- Uses TaskRunBuilder to construct complete TaskRun
- Creates TaskRun using taskRunClient
- Logs created resource name to console

**`paramsToParamList(): List<Param>`**
- Converts List<TektonParam> to List<Param>
- Creates Param objects with name and ArrayOrString value
- Handles string parameter values
- Returns: List of Tekton Param objects

**`workspacesToWorkspaceBindingList(): List<WorkspaceBinding>`**
- Converts List<TektonWorkspaceBind> to List<WorkspaceBinding>
- Creates WorkspaceBinding objects with name and PersistentVolumeClaimVolumeSource
- Sets readOnly=false for all PVC bindings
- Returns: List of WorkspaceBinding objects

**`logTektonTaskrun(): void`**
- Logs TaskRun configuration to Jenkins console
- Outputs: Kind, Name, Namespace, TaskRef
- Used for debugging and transparency

## Part 2: Tekton Resource Deletion

### 1. Raw Resource Deletion (`DeleteRaw` class)

#### Core Deletion Functions:

**`deleteTask(): Boolean`**
- Lists all Task resources using taskClient.list().getItems()
- If resourceName is null: deletes all tasks using `taskClient.delete(taskList)`
- If resourceName provided:
- Iterates through task list to find matching name
- Deletes specific task using `taskClient.delete(task)`
- Returns: Boolean indicating successful deletion

**`deleteTaskRun(): Boolean`**
- Lists all TaskRun resources using taskRunClient.list().getItems()
- If resourceName is null: deletes all task runs using `taskRunClient.delete(taskRunList)`
- If resourceName provided:
- Iterates through task run list to find matching name
- Deletes specific task run using `taskRunClient.delete(taskRun)`
- Returns: Boolean indicating successful deletion

**`deletePipeline(): Boolean`**
- Lists all Pipeline resources using pipelineClient.list().getItems()
- If resourceName is null: deletes all pipelines using `pipelineClient.delete(pipelineList)`
- If resourceName provided:
- Iterates through pipeline list to find matching name
- Deletes specific pipeline using `pipelineClient.delete(pipeline)`
- Returns: Boolean indicating successful deletion

**`deletePipelineRun(): Boolean`**
- Lists all PipelineRun resources using pipelineRunClient.list().getItems()
- If resourceName is null: deletes all pipeline runs using `pipelineRunClient.delete(pipelineRunList)`
- If resourceName provided:
- Iterates through pipeline run list to find matching name
- Deletes specific pipeline run using `pipelineRunClient.delete(pipelineRun)`
- Returns: Boolean indicating successful deletion

**`deleteWithResourceSpecificClient(TektonResourceType resourceType): boolean`**
- Router method that delegates to specific deletion functions
- Switch statement handles: task, taskrun, pipeline, pipelinerun
- Returns: Result from specific deletion function (boolean)

**`runDelete(): boolean`**
- Main orchestration method for resource deletion
- Calls `deleteWithResourceSpecificClient()` with configured resource type
- Returns: Boolean indicating deletion success

## Part 3: Infrastructure Functions

### Resource Detection:

**`TektonUtils.getKindFromInputStream(InputStream inputStream, String inputType): List<TektonResourceType>`**
- Reads input stream and converts to string
- Splits YAML content by line separator
- Searches for lines starting with "kind"
- Extracts kind value and converts to lowercase
- Maps to TektonResourceType enum values
- Returns: List of detected resource types
- Handles: IOException during stream reading

### Client Management:

**`TektonUtils.initializeKubeClients(Config config): void`**
- Creates TektonClient and KubernetesClient from config
- Stores clients in static maps with DEFAULT_CLIENT_KEY
- Thread-safe using synchronized methods

**`TektonUtils.initializeKubeClients(List<ClusterConfig> clusterConfigs): void`**
- Creates clients for multiple cluster configurations
- Builds Config objects from ClusterConfig (masterUrl, namespace)
- Stores clients in maps using cluster name as key
- Adds default clients if not present

**`TektonUtils.shutdownKubeClients(): void`**
- Closes all TektonClient and KubernetesClient instances
- Iterates through client maps and calls close() on each
- Thread-safe cleanup of resources

### Utility Functions:

**`LogUtils.logStream(InputStream in, Logger logger, boolean error): void`**
- Reads input stream line by line using LineReader
- Logs each line to specified logger
- Uses Level.WARNING for error streams, Level.INFO for regular streams
- Handles: IOException during stream reading

**`ToolUtils.getJXPipelineBinary(ClassLoader classLoader): String`**
- Detects platform (Linux, macOS, Windows) using SystemUtils
- Extracts appropriate jx-pipeline-effective binary from classpath
- Creates temporary file and copies binary content
- Sets executable permissions on binary file
- Returns: File path to executable binary
- Throws: IOException if extraction or permission setting fails

## Part 4: Dependencies and Libraries

### Core Tekton/Kubernetes Libraries
- **fabric8 Kubernetes Client** (`io.fabric8.kubernetes`)
- `DefaultKubernetesClient` - Main Kubernetes API client
- `Config`, `ConfigBuilder` - Kubernetes cluster configuration
- Custom Resource Definition support

- **fabric8 Tekton Client** (`io.fabric8.tekton`)
- `DefaultTektonClient` - Tekton-specific API client
- `TektonClient` - Interface for Tekton operations
- Tekton v1beta1 API models:
- `Task`, `TaskList`, `TaskRun`, `TaskRunList`
- `Pipeline`, `PipelineList`, `PipelineRun`, `PipelineRunList`
- `Param`, `ArrayOrString`, `WorkspaceBinding`

### Jenkins Core Libraries
- **Hudson/Jenkins Core**
- `hudson.tasks.Builder` - Base class for build steps
- `hudson.model.Run`, `hudson.model.TaskListener`
- `hudson.FilePath`, `hudson.Launcher`
- `hudson.EnvVars` - Environment variable handling

- **Jenkins Pipeline Support**
- `jenkins.tasks.SimpleBuildStep` - Pipeline step interface
- `org.jenkinsci.Symbol` - Pipeline step annotations

- **Jenkins Checks API** (`io.jenkins.plugins.checks.api`)
- `ChecksPublisher`, `ChecksDetails`, `ChecksOutput`
- `ChecksStatus`, `ChecksConclusion`
- GitHub-style status reporting

### Utility Libraries
- **Google Guava**
- `com.google.common.io.LineReader` - Line-by-line stream reading
- `com.google.common.io.Resources`, `ByteStreams`
- `com.google.common.base.Strings` - String utilities

- **Apache Commons**
- `org.apache.commons.lang.SystemUtils` - Platform detection
- `org.apache.commons.lang.StringUtils` - String operations

- **Jackson YAML Processing**
- `com.fasterxml.jackson.databind.ObjectMapper`
- `com.fasterxml.jackson.dataformat.yaml.YAMLFactory`
- YAML serialization for logging