📚 Sync docs from alaudadevops/tektoncd-operator on 50edd5065f3d778e6b7361de15fd225e826c5e78

Source: docs(results): clarify tkn-results quick start (#1539)
Author: l-qing
Ref: refs/heads/release-4.0
Commit: 50edd5065f3d778e6b7361de15fd225e826c5e78

This commit automatically syncs documentation changes from the source-docs repository.

🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/50edd5065f3d778e6b7361de15fd225e826c5e78
🤖 Synced on 2026-03-31 16:09:42 UTC

Author: edge-katanomi-app2[bot]

.github/SYNC_INFO.md

@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2026-03-30 13:24:46 UTC
+- **Last synced**: 2026-03-31 16:09:42 UTC
 - **Source repository**: alaudadevops/tektoncd-operator
-- **Source commit**: [dab5aa32dec0742c4a9b2b17a3c6f16f86d1175e](https://github.com/alaudadevops/tektoncd-operator/commit/dab5aa32dec0742c4a9b2b17a3c6f16f86d1175e)
+- **Source commit**: [50edd5065f3d778e6b7361de15fd225e826c5e78](https://github.com/alaudadevops/tektoncd-operator/commit/50edd5065f3d778e6b7361de15fd225e826c5e78)
 - **Triggered by**: edge-katanomi-app2[bot]
-- **Workflow run**: [#167](https://github.com/alaudadevops/tektoncd-operator/actions/runs/23747030875)
+- **Workflow run**: [#173](https://github.com/alaudadevops/tektoncd-operator/actions/runs/23807382418)
 
 ## Files synced:
 - docs/

docs/en/install.mdx

@@ -324,6 +324,6 @@ spec:
 
 After successfully installing the Alauda DevOps Pipelines Operator:
 
-- [Adjusting Optional Configuration Items of Subcomponents](../configure/customize_options)
-- [Configuring Resource Quotas for Pipeline Components](../configure/customize_tekton_pipeline)
-- [Regular Cleanup of TaskRun and PipelineRun Resources](../configure/pruner_resources)
+- [Adjusting Optional Configuration Items of Subcomponents](./configure/customize_options.mdx)
+- [Configuring Resource Quotas for Pipeline Components](./configure/customize_tekton_pipeline.mdx)
+- [Regular Cleanup of TaskRun and PipelineRun Resources](./configure/pruner_resources.mdx)

docs/en/overview/release_notes.mdx

@@ -14,7 +14,7 @@ title: Release Notes
 The maintenance period for version **v4.0.z** is from April 8, 2025 to April 8, 2026.
 :::
 
-## Compatibility and support matrix
+## Compatibility and support matrix \{#compatibility-and-support-matrix}
 
 The following table shows the compatibility and support matrix between the `Alauda DevOps Pipelines` operator and ACP versions.
 

docs/en/results/quick_start.mdx

@@ -201,7 +201,7 @@ hello                                        True        Succeeded   11s
 ```yaml
 $ cat <<EOF | kubectl create -f -
 apiVersion: rbac.authorization.k8s.io/v1
-kind: Role
+kind: ClusterRole
 metadata:
   name: tekton-results-readonly
 rules:
@@ -241,7 +241,6 @@ apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
   name: tekton-results-user
-  namespace: default
 subjects:
   - kind: ServiceAccount
     name: impersonate-user
@@ -313,6 +312,9 @@ $ curl -s -k \
 > [tkn](https://github.com/tektoncd/cli/releases) is a command-line tool for interacting with Tekton. You can download it from the [official page](https://github.com/tektoncd/cli/releases).
 >
 > You need to build [tkn-results](https://github.com/tektoncd/results/blob/main/cmd/tkn-results/main.go) using golang.
+>
+> Do not always build from `main`. Use the release branch that matches the Tekton Results version deployed in your environment.
+> You can find the Results component version in [Release Notes](../overview/release_notes.mdx#compatibility-and-support-matrix) (the `Results` column), and then checkout the corresponding branch `release-v<version>.x`.
 
 ```sh
 # 1. Clone the repository
@@ -321,12 +323,25 @@ git clone https://github.com/tektoncd/results.git
 # 2. Change to the project directory
 cd results
 
-# 3. Build the binary
+# 3. Checkout the matching release branch (example: Results 0.15.x -> release-v0.15.x)
+git checkout release-v<version>.x
+
+# 4. Build the binary
 go build -o tkn-results ./cmd/tkn-results/main.go
 
-# 4. Copy the binary to a directory in your PATH
+# 5. Copy the binary to a directory in your PATH
 ```
 
+##### Connection behavior
+
+> When `--addr` is not set, `tkn-results` attempts to auto port-forward to the Results API service.
+>
+> In many versions (including `release-v0.15.x`), the auto target is `tekton-pipelines/tekton-results-api-service`.
+> If your Results deployment uses a different namespace or service name, auto mode may fail.
+>
+> When `--addr` is set, `tkn-results` connects to that address directly.
+> In that case, you typically need to run `kubectl port-forward` yourself.
+
 ##### Querying the execution record list
 
 ```sh
@@ -336,6 +351,19 @@ default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/209dcb81-e3c0-47cd-
 default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/a750035d-0479-34a1-9db2-9a256b53243f  results.tekton.dev/v1alpha3.Log         2025-02-19 16:17:21 +0800 CST           2025-02-19 16:17:21 +0800 CST
 ```
 
+##### Fallback when auto port-forward fails
+
+```sh
+$ kubectl port-forward -n <results-namespace> service/tekton-results-api-service 8080
+
+$ tkn results --insecure --addr localhost:8080 records list default/results/-
+$ tkn results --insecure --addr localhost:8080 records get -o textproto default/results/<result-uid>/records/<record-uid>
+$ tkn results --insecure --addr localhost:8080 logs list default/results/-
+$ tkn results --insecure --addr localhost:8080 logs get -o textproto default/results/<result-uid>/logs/<log-uid>
+# If logs get returns "unknown service tekton.results.v1alpha3.Logs", retry with:
+$ tkn results --insecure --addr localhost:8080 --v1alpha2 logs get -o textproto default/results/<result-uid>/logs/<log-uid>
+```
+
 ##### Querying a single execution record
 
 ```sh
@@ -377,6 +405,9 @@ default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/logs/a750035d-0479-34a1-9db
 
 ##### Querying a single log
 
+> The Logs API version may vary by deployment.
+> If you encounter `unknown service tekton.results.v1alpha3.Logs`, retry the command with the `--v1alpha2` flag.
+
 ```sh
 $ tkn results --insecure logs get -o textproto default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/logs/a750035d-0479-34a1-9db2-9a256b53243f