feat : add consistent exit codes by vikashkumar2020 · Pull Request #3130 · tektoncd/cli

vikashkumar2020 · 2026-08-11T18:49:43Z

Changes

Fixes : #2855
Implemented consistent exit codes across tkn. Added a new pkg/exitcode package defining codes 0–5 (success, general error, not found, invalid input, timeout, unauthorized) with a typed error that propagates through the call stack. All Kubernetes API calls in pkg/actions now classify errors at the boundary via exitcode.FromAPIError(). The root command wires up exitcode.CodeFrom() to drive os.Exit, and adds structured {"error":"…","code":N} JSON output to stderr when --output json is set. A reference doc at docs/exit-codes.md covers the full scheme with examples.

Submitter Checklist

These are the criteria that every PR should meet, please check them off as you
review them:

Includes tests (if functionality changed/added)
Run the code checkers with make check
Regenerate the manpages, docs and go formatting with make generated
Commit messages follow commit message best practices

See the contribution guide
for more details.

Release Notes

Add consistent exit codes to tkn: 0 success, 1 general error, 2 not found, 3 invalid input, 4 timeout, 5 unauthorized/forbidden. Kubernetes API errors are now classified at the boundary with typed errors, and `--output json` emits a structured {"error":"...","code":N} object on stderr. `tkn pipelinerun logs --exit-with-error` now exits 1 (general error) instead of 2 when the PipelineRun has no conditions yet.

tekton-robot · 2026-08-11T18:49:47Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign divyansh42 after the PR has been reviewed.
You can assign the PR to them by writing /assign @divyansh42 in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

divyansh42 · 2026-08-12T03:54:29Z

@vikashkumar2020 thanks for the PR!
Could you please add release notes and link it to the corresponding GitHub issue?

vikashkumar2020 · 2026-08-12T04:09:33Z

@vikashkumar2020 thanks for the PR! Could you please add release notes and link it to the corresponding GitHub issue?

added into description

divyansh42

The PR wraps errors in pkg/actions (get, list, delete, patch) but many commands produce errors through other paths: direct client calls in trigger/bundle commands, flag validation errors in RunE, etc. The issue asks for consistent exit codes "across all commands."

This is acceptable as a first pass, but please file a follow-up issue tracking the remaining commands so this doesn't fall through the cracks.

Copilot

Pull request overview

Implements a shared exit-code scheme for tkn by introducing a typed error that carries an intended exit code, classifying certain Kubernetes API failures at the pkg/actions boundary, and wiring the top-level CLI entrypoint to exit using the resolved code (with documentation for consumers).

Changes:

Added pkg/exitcode with standard codes (0–5), a typed exitcode.Error, and Kubernetes API error classification helpers.
Updated the top-level command execution path to silence Cobra’s default error printing and to drive os.Exit(...) from exitcode.CodeFrom(err), plus structured JSON error output support.
Updated selected actions helpers to wrap API errors via exitcode.FromAPIError(...) and aligned pipelinerun logs --exit-with-error behavior with the new scheme.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pkg/exitcode/exitcode.go	Defines exit codes, typed error, and K8s API error classification.
pkg/exitcode/exitcode_test.go	Unit tests for `CodeFrom` and `FromAPIError`.
pkg/cmd/root.go	Silences Cobra errors and adds `PrintError` to emit JSON error payloads for `--output json`.
cmd/tkn/main.go	Switches to centralized error printing + exit code resolution.
pkg/actions/get.go	Wraps dynamic client `Get` errors via `exitcode.FromAPIError`.
pkg/actions/list.go	Wraps dynamic client `List` errors via `exitcode.FromAPIError`.
pkg/actions/delete.go	Wraps dynamic client `Delete` errors via `exitcode.FromAPIError`.
pkg/actions/patch.go	Wraps dynamic client `Patch` errors via `exitcode.FromAPIError`.
pkg/cmd/pipelinerun/logs.go	Adjusts “no conditions” exit code to avoid conflicting with NotFound.
pkg/cmd/pipelinerun/logs_test.go	Updates the corresponding unit test expectation.
docs/exit-codes.md	Documents the exit code table, examples, and structured JSON stderr errors.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

divyansh42 · 2026-08-28T09:44:25Z

One more minor comment:
The new files have Copyright © 2024 but this PR is authored in 2026. Please update to 2026.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Suppressed comments (2)

cmd/tkn/main.go:53

PrintError is given the root command, but --output is a local flag on the executed leaf command (PrintFlags.AddFlags uses cmd.Flags()). The lookup therefore fails and is ignored, so even tkn pipelinerun describe missing --output json emits the plain-text error instead of JSON. Use ExecuteC and pass its returned command; an integration test with a leaf --output json flag would catch this.

	if err := tkn.Execute(); err != nil {
		tknCmd.PrintError(tkn, err, os.Stderr)

pkg/actions/list.go:61

The API-boundary audit is incomplete. pkg/actions/create.go:34 and pkg/actions/watch.go:35 still return raw Kubernetes API errors, so commands using actions.Create or actions.Watch return code 1 for forbidden or timeout responses instead of codes 5 or 4. Apply the same classification to every API operation in this package.

	allRes, err := dynamic.Resource(*gvr).Namespace(ns).List(context.Background(), op)
	if err != nil {
		return nil, exitcode.FromAPIError(err)

divyansh42 · 2026-10-05T08:54:44Z

@vikashkumar2020 is there any update on this?

divyansh42 · 2026-10-16T07:40:47Z

@vikashkumar2020 is there any update on this?

vikashkumar2020 · 2026-10-29T08:32:09Z

@vikashkumar2020 is there any update on this?

Hi, due to some complications around the contribution to open source in my org at IBM. I have to hold on making any further contribution

divyansh42 · 2026-10-29T09:14:10Z

@vikashkumar2020 is there any update on this?

Hi, due to some complications around the contribution to open source in my org at IBM. I have to hold on making any further contribution

Thanks, @vikashkumar2020 for informing us.
We will take your commits and create another PR with these changes so that we can unblock this feature.
I hope that is fine.

I hope you come back to contribute to this project. Thank you for your contributions. 🙂

divyansh42 · 2026-11-02T09:29:59Z

/retest

divyansh42 · 2026-11-02T12:53:46Z

/retest

divyansh42 · 2026-11-02T19:09:21Z

/retest

divyansh42 · 2026-11-03T09:02:43Z

@copilot review

Copilot

🟡 Changes recommended

Unresolved error classification and propagation gaps produce incorrect exit codes, while direct stderr diagnostics and inconsistent output-mode handling break the JSON error contract.

14 open issues

Preserve typed errors through description, list, cancel, and delete paths · New
Classify Cobra parsing and validation failures as InvalidInput · New
Normalize output format before selecting structured error rendering · New
Resolve output mode even when flag parsing fails · New
Map client and server timeouts to the Timeout exit code · New
Map Kubernetes Invalid and BadRequest errors to InvalidInput · New
Classify untyped Kubernetes API errors before the GeneralError fallback · New
Classifying at this boundary is not sufficient to make the code reach main: several existing…
Exit code 3 is currently unreachable in production: no command or validator creates an…
k8serrors.IsTimeout does not match Kubernetes StatusReasonServerTimeout; that case has the…
The PR description states that all Kubernetes API calls in pkg/actions classify errors via…
FromAPIError doesn’t currently map Kubernetes validation/client errors (e.g. HTTP 400/422) to…
This function prints a plain-text message directly to stderr before returning the error. With the…
New behavior in PrintError (structured JSON to stderr when --output json) isn’t covered by unit…

1 resolved since last review

PrintError is currently called with the root command (tkn), but most --output flags are…

_{Review effort: Max}

divyansh42 · 2026-11-05T04:25:30Z

/retest

Copilot

🟡 Changes recommended

Existing command paths lose classified error causes, validation failures return incorrect exit codes, and JSON error output depends on flag order.

11 open issues

6 resolved since last review

Classify untyped Kubernetes API errors before the GeneralError fallback
Map Kubernetes Invalid and BadRequest errors to InvalidInput
Normalize output format before selecting structured error rendering
k8serrors.IsTimeout does not match Kubernetes StatusReasonServerTimeout; that case has the…
FromAPIError doesn’t currently map Kubernetes validation/client errors (e.g. HTTP 400/422) to…
This function prints a plain-text message directly to stderr before returning the error. With the…

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

Command handlers still discard classified API errors and leave input errors unclassified, producing incorrect exit codes, while JSON error output inconsistently depends on flag order.

12 open issues

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

Unresolved error-handling defects produce incorrect exit codes for invalid input and wrapped API failures, while malformed flags make JSON error output depend on argument order.

13 open issues

1 resolved since last review

Use the registered PipelineRun logs flag in the documentation

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

Lost API error causes and unclassified client-side input errors produce incorrect exit codes, while JSON error output depends on flag order.

10 open issues

4 resolved since last review

_{Review effort: Balanced}

Introduce a pkg/exitcode package that defines the standard tkn exit codes (0 success, 1 general error, 2 not found, 3 invalid input, 4 timeout, 5 unauthorized) and a typed error so that errors can carry their intended exit code through the call stack. Classify Kubernetes API errors at the boundary in the shared actions layer (get, list, delete, patch) via exitcode.FromAPIError, and emit the resolved code from main using exitcode.CodeFrom. When --output json is set, errors are written to stderr as a structured {"error":"...","code":N} payload. Document the full scheme in docs/exit-codes.md. Closes tektoncd#2855 Signed-off-by: Vikash Kumar <kvvik2020@gmail.com>

Build on the exit-code support with correctness and coverage fixes: - FromAPIError now keeps the original Kubernetes error as the wrapped error and exposes it via Unwrap, so k8serrors helpers such as IsNotFound/IsForbidden still match after classification. Replacing the typed error broke callers like customrun delete that branch on IsNotFound. - main passes the command returned by ExecuteC (the one that actually ran) to PrintError, and PrintError takes an io.Writer. --output is a subcommand-local flag, so reading it from the root command meant the structured {"error":...,"code":N} JSON output never triggered. PrintError now normalizes the flag so "JSON"/"Json" also match. - Classify invalid/bad-request errors as InvalidInput (3) and timeout/server-timeout/context.DeadlineExceeded as Timeout (4) via a shared classify helper, and let CodeFrom fall back to it for raw Kubernetes/context errors preserved by intermediate callers. - Wrap Create and Watch API errors through FromAPIError, and drop the stray stderr message in Patch so failures surface only as the typed error. - Align the --exit-with-pipelinerun-error help text (pipelinerun logs and pipeline start) and regenerated docs/man pages with the new "no conditions" behavior, which now exits 1 instead of 2. - Document that code 2 (not found) intentionally diverges from the Bash "misuse of builtins" convention, and reference the real --exit-with-pipelinerun-error flag name in docs/exit-codes.md. Address review follow-ups so the documented codes actually reach the caller and cover client-side input errors: - Preserve the error cause with %w across the describe, list, cancel and delete paths that previously formatted it with %v/%s or discarded it (for example pkg/taskrun/description.go, pkg/cmd/pipeline/list.go and pkg/deleter/deleter.go). NotFound and Forbidden now propagate through CodeFrom regardless of output format. Where a caller must keep an exact message without the cause, it returns exitcode.New(CodeFrom(err), ...) so the code is retained. - Classify client-side input errors as InvalidInput (3): a root SetFlagErrorFunc tags flag-parsing failures, a visitCommands pass wraps positional-argument validators, and option validators (negative --limit and invalid --output/kind) are wrapped at their source. - Resolve the requested --output mode independently of successful flag parsing. Cobra stops at the first invalid flag, so PrintError now falls back to scanning the raw arguments (honoring the -- terminator) and the JSON error format no longer depends on flag order. Signed-off-by: divyansh42 <diagrawa@redhat.com> Assisted-by: Claude Opus 4.8 (via GitHub Copilot CLI) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Argument validation incorrectly reclassifies API errors, while output-format detection mishandles option values and defaults, causing incorrect exit codes and error formats.

3 open issues

10 resolved since last review

_{Review effort: Balanced}

+	if outputFlag == "" {
+		outputFlag = outputFromArgs(os.Args[1:])
+	}


+		case strings.HasPrefix(a, "-o") && len(a) > 2:
+			return a[2:]


+		if err := orig(c, args); err != nil {
+			return exitcode.New(exitcode.InvalidInput, "%s", err)


tekton-robot added the release-note Denotes a PR that will be considered when it comes time to generate release notes. label Aug 11, 2026

tekton-robot requested review from divyansh42 and pratap0007 August 11, 2026 18:49

tekton-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Aug 11, 2026

divyansh42 requested changes Aug 28, 2026

View reviewed changes

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread pkg/cmd/root.go Resolved

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread pkg/cmd/pipelinerun/logs.go Resolved

Comment thread docs/exit-codes.md Resolved

divyansh42 requested a lite review from Copilot August 28, 2026 07:37

Copilot started reviewing on behalf of divyansh42 August 28, 2026 07:38

View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Comment thread cmd/tkn/main.go Resolved

Comment thread pkg/actions/patch.go Resolved

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread pkg/actions/list.go Resolved

Comment thread pkg/cmd/root.go Resolved

divyansh42 requested a balanced review from Copilot August 28, 2026 10:12

Copilot started reviewing on behalf of divyansh42 August 28, 2026 10:13

View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread pkg/exitcode/exitcode.go Resolved

divyansh42 requested a balanced review from Copilot October 20, 2026 13:47

divyansh42 force-pushed the feature/consistent-exit-codes branch from 034007f to b94d1b2 Compare November 2, 2026 08:51

divyansh42 force-pushed the feature/consistent-exit-codes branch from b94d1b2 to c095e71 Compare November 2, 2026 12:54

divyansh42 closed this Nov 3, 2026

divyansh42 reopened this Nov 3, 2026

divyansh42 requested a max review from Copilot and removed request for Copilot November 3, 2026 09:03

Copilot started reviewing on behalf of divyansh42 November 3, 2026 09:04

View session

Copilot AI reviewed Nov 3, 2026

View reviewed changes

divyansh42 force-pushed the feature/consistent-exit-codes branch from c095e71 to 5b41f4b Compare November 4, 2026 20:30

tekton-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Nov 4, 2026

divyansh42 requested a balanced review from Copilot November 5, 2026 04:24

Copilot started reviewing on behalf of divyansh42 November 5, 2026 04:25

View session

Copilot AI reviewed Nov 5, 2026

View reviewed changes

Comment thread pkg/exitcode/exitcode.go Resolved

Comment thread docs/exit-codes.md Resolved

Comment thread pkg/cmd/pipelinerun/logs.go Resolved

chmouel requested a balanced review from Copilot November 6, 2026 10:10

Copilot started reviewing on behalf of chmouel November 6, 2026 10:10

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Comment thread pkg/cmd/root.go Resolved

divyansh42 force-pushed the feature/consistent-exit-codes branch from 5b41f4b to d4afff0 Compare November 11, 2026 12:19

divyansh42 requested a balanced review from Copilot November 11, 2026 12:38

Copilot started reviewing on behalf of divyansh42 November 11, 2026 12:39

View session

Copilot AI reviewed Nov 11, 2026

View reviewed changes

Comment thread cmd/tkn/main.go Resolved

Comment thread pkg/exitcode/exitcode.go Resolved

divyansh42 requested a balanced review from Copilot November 11, 2026 13:34

Copilot started reviewing on behalf of divyansh42 November 11, 2026 13:34

View session

Copilot AI reviewed Nov 11, 2026

View reviewed changes

Comment thread pkg/actions/get.go Resolved

divyansh42 force-pushed the feature/consistent-exit-codes branch from d4afff0 to cb85acc Compare November 11, 2026 14:48

tekton-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 11, 2026

vikashkumar2020 and others added 2 commits November 11, 2026 20:24

divyansh42 force-pushed the feature/consistent-exit-codes branch from cb85acc to a2f3bfb Compare November 11, 2026 14:59

tekton-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 11, 2026

divyansh42 requested a balanced review from Copilot November 11, 2026 15:00

Copilot started reviewing on behalf of divyansh42 November 11, 2026 15:00

View session

Copilot AI reviewed Nov 11, 2026

View reviewed changes

		if err := orig(c, args); err != nil {
		return exitcode.New(exitcode.InvalidInput, "%s", err)

Conversation

vikashkumar2020 commented Aug 11, 2026 • edited by divyansh42 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Submitter Checklist

Release Notes

Uh oh!

tekton-robot commented Aug 11, 2026

Uh oh!

divyansh42 commented Aug 12, 2026

Uh oh!

vikashkumar2020 commented Aug 12, 2026

Uh oh!

divyansh42 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

divyansh42 commented Aug 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

divyansh42 commented Oct 5, 2026

Uh oh!

divyansh42 commented Oct 16, 2026

Uh oh!

vikashkumar2020 commented Oct 29, 2026

Uh oh!

divyansh42 commented Oct 29, 2026

Uh oh!

divyansh42 commented Nov 2, 2026

Uh oh!

divyansh42 commented Nov 2, 2026

Uh oh!

divyansh42 commented Nov 2, 2026

Uh oh!

divyansh42 commented Nov 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

divyansh42 commented Nov 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

vikashkumar2020 commented Aug 11, 2026 •

edited by divyansh42

Loading