-
Story
-
Resolution: Done
-
Major
-
None
-
None
-
None
Story (Required)
As a Tekton CLI (tkn) user troubleshooting failed PipelineRuns and TaskRuns,
I want to invoke tekton-assist directly from the CLI,
so that I can quickly get structured root cause analysis and remediation steps without leaving my terminal.
High-level purpose: This story ensures the tekton-assist service is consumable from the Tekton CLI. By embedding failure analysis into tkn, users benefit from immediate, actionable insights in the same workflow where they currently inspect logs and statuses. This improves efficiency and reduces context-switching during debugging.
Background (Required)
tkn is the primary command-line interface for interacting with Tekton resources. Today, users typically run commands like tkn pipelinerun describe or tkn taskrun logs to investigate failures. These outputs are verbose and require expertise to interpret.
By integrating with the tekton-assist service, tkn will gain an explain subcommand (or flag) that calls the service API and displays a human-readable failure analysis report. This bridges the gap between raw logs and actionable insights, helping users resolve issues faster.
Out of scope
- Retrieval-Augmented Generation (RAG) or knowledge-base-backed reasoning.
- Console UI integration (covered by separate story).
- Advanced agentic workflows.
Approach (Required)
Add subcommand to tkn:
tkn taskrun explain <name> -n <namespace>
tkn constructs request JSON:
{
"namespace": "default",
"taskRun": "mytaskrun"
}
Response Parsing & Pretty Print
Response API
{
"debug": {
"taskrun": "pipelinerun-go-golangci-lint",
"namespace": "default",
"succeeded": false,
"failed_step": {
"name": "lint",
"exit_code": 3
},
"error": {
"type": "Succeeded",
"status": "False",
"reason": "Failed",
"message": "\"step-lint\" exited with code 3: Error",
"log_snippet": "level=info msg=\"[config_reader] Config search paths: [./ /workspace/src /workspace / /root]\"\nlevel=info msg=\"[lintersdb] Active 10 linters: [deadcode errcheck gosimple govet ineffassign staticcheck structcheck typecheck unused varcheck]\"\nlevel=info msg=\"[loader] Go packages loading at mode 575 (types_sizes|deps|exports_file|imports|name|compiled_files|files) took 115.369441ms\"\nlevel=error msg=\"Running error: context loading failed: failed to load packages: failed to load with go/packages: err: exit status 1: stderr: go: errors parsing go.mod:\\n/workspace/src/go.mod:3: invalid go version '1.21.3': must match format 1.23\\n\"\nlevel=info msg=\"Memory: 3 samples, avg is 71.8MB, max is 71.8MB\"\nlevel=info msg=\"Execution took 125.427795ms\""
}
},
"analysis": "* **Root Cause**: The `go.mod` file declares `go 1.21.3`, but the Go toolchain installed in the `lint` step's container environment is expecting a `go.mod` format compatible with `1.23` (likely running Go 1.23 or newer), causing a parsing error.\n* **Likely Failing Component**: The container image used for the `lint` step.\n* **Concrete Remediation Steps**:\n * **Update `go.mod`**: Modify the `go.mod` file in your repository to `go 1.23` to align with the Go version in the `lint` container.\n * **Change Container Image**: Update the `lint` step's `image` in the Tekton Task to use a `golangci-lint` image that is built with or compatible with Go `1.21.3` (e.g., `golangci/golangci-lint:latest-go1.21`)."
}
Prettfying
Tekton TaskRun Failure Report TaskRun: pipelinerun-go-golangci-lint Namespace: default Succeeded: ❌ No Failed Step: lint Exit Code: 3 Error Details: Type: Succeeded Status: False Reason: Failed Message: "step-lint" exited with code 3: Error Log Snippet: level=info msg="[config_reader] Config search paths: [./ /workspace/src /workspace / /root]" level=info msg="[lintersdb] Active 10 linters: [deadcode errcheck gosimple govet ineffassign staticcheck structcheck typecheck unused varcheck]" level=info msg="[loader] Go packages loading at mode 575 (types_sizes|deps|exports_file|imports|name|compiled_files|files) took 115.369441ms" level=error msg="Running error: context loading failed: failed to load packages: failed to load with go/packages: err: exit status 1: stderr: go: errors parsing go.mod:\n/workspace/src/go.mod:3: invalid go version '1.21.3': must match format 1.23\n" level=info msg="Memory: 3 samples, avg is 71.8MB, max is 71.8MB" level=info msg="Execution took 125.427795ms" Analysis & Suggested Remediation: * **Root Cause**: The `go.mod` file specifies an invalid Go version format (`1.21.3`), which is rejected by the Go toolchain invoked by `golangci-lint`. * **Likely Failing Component**: The application's `go.mod` file, which is consumed by the `lint` step's `golangci-lint` command. * **Remediation Steps**: * **Edit `go.mod`**: Change the Go version entry in `/workspace/src/go.mod` from `go 1.21.3` to `go 1.21` (or the intended major.minor version, e.g., `go 1.22`). * **Verify Go Toolchain**: Ensure the container image used for the `lint` step provides a Go toolchain version that is compatible with or newer than the version specified in `go.mod`. * **Update `golangci-lint`**: Consider updating the `golangci-lint` version used in your Task to ensure compatibility with your project's Go version. ➜ ~
Dependencies
<Describes what this story depends on. Dependent Stories and EPICs should be linked to the story.>
Acceptance Criteria (Mandatory)
<Describe edge cases to consider when implementing the story and defining tests>
<Provides a required and minimum list of acceptance tests for this story. More is expected as the engineer implements this story>
INVEST Checklist
Dependencies identified
Blockers noted and expected delivery timelines set
Design is implementable
Acceptance criteria agreed upon
Story estimated
Legend
Unknown
Verified
Unsatisfied
Done Checklist
- Code is completed, reviewed, documented and checked in
- Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
- Continuous Delivery pipeline(s) is able to proceed with new code included
- Customer facing documentation, API docs etc. are produced/updated, reviewed and published
- Acceptance criteria are met