openshift · mramendi · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025
diff --git a/modules/op-prepare-opc-for-results.adoc b/modules/op-prepare-opc-for-results.adoc
@@ -12,6 +12,7 @@ Before you can query {tekton-results}, you must prepare the environment for the
 .Prerequisites
 
 * You installed the `opc` utility.
+* You logged on to the {OCP} cluster using the {oc-first}.
 
 .Procedure
 
@@ -29,6 +30,8 @@ $ export RESULTS_API=$(oc get route tekton-results-api-service -n openshift-pipe
 $ oc create token <service_account>
 ----
 +
+Replace `<service_account>` with the name of an {OCP} service account that has read access to the namespaces where {pipelines-shortname} ran the pipeline runs and task runs.
++
 Save the string that this command outputs.
 
 . Optional: Create the `~/.config/tkn/results.yaml` file for automatic authentication with the {tekton-results} API. The file must have the following contents:

diff --git a/modules/op-query-results-name.adoc b/modules/op-query-results-name.adoc
@@ -21,13 +21,13 @@ You can list and query results and records using their names.
 +
 [source,terminal]
 ----
-$ opc results list --addr ${RESULTS_API} <namespace_name>
+$ opc results result list --addr ${RESULTS_API} <namespace_name>
 ----
 +
 .Example command
 [source,terminal]
 ----
-$ opc results list --addr ${RESULTS_API} results-testing
+$ opc results result list --addr ${RESULTS_API} results-testing
 ----
 +
 .Example output

diff --git a/modules/op-results-concepts.adoc b/modules/op-results-concepts.adoc
@@ -170,4 +170,9 @@ $ oc get pipelinerun <cr_name> -o yaml
 
 You can access every result and record by its name. You can also use Common Expression Language (CEL) queries to search for results and records by the information they contain, including the YAML manifest.
 
-You can also configure {tekton-results} to facilitate forwarding the logging information of all the tools that ran as a part of a pipeline or task to LokiStack. You can then query {tekton-results} for logging information of the task run associated with a {tekton-results} record.
+You can configure {tekton-results} to facilitate forwarding the logging information of all the tools that ran as a part of a pipeline or task to LokiStack. You can then query {tekton-results} for logging information of the task run associated with a {tekton-results} record.
+
+You can also query results and logs by the names of pipeline runs and task runs.
+
+:FeatureName: Querying results and logs by the names of pipeline runs and task runs
+include::snippets/technology-preview.adoc[]
diff --git a/modules/op-results-opc-config.adoc b/modules/op-results-opc-config.adoc
@@ -0,0 +1,69 @@
+// This module is included in the following assembly:
+//
+// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="results-opc-config_{context}"]
+= Configuring the opc utility for querying results by pipeline run and task run names
+
+[role="_abstract"]
+Before you can query results from {tekton-results} by pipeline run and task run names, you must configure the `opc` utility.
+
+.Prerequisites
+
+* You installed the `opc` utility.
+* You logged on to the {OCP} cluster using the {oc-first}.
+
+.Procedure
+
+. Create an authentication token for the {tekton-results} API by entering the following command:
++
+[source,terminal]
+----
+$ oc create token <service_account>
+----
++
+Replace `<service_account>` with the name of an {OCP} service account that has read access to the namespaces where {pipelines-shortname} ran the pipeline runs and task runs.
++
+Save the string that this command outputs.
+
+. Complete one of the following steps:
+
+** Configure the `opc` utility interactively by entering the following command:
++
+[source,terminal]
+----
+$ opc results config set
+----
++
+Reply to the prompts that the utility displays. For `Token`, enter the authentication token that you created.
+
+** Configure the `opc` utility from a command by entering the following command:
++
+[source,terminal]
+----
+$ opc results config set --host="https://tekton-results.example.com" --token="sha256~xyz"
+----
++
+Replace the host name with the fully qualified domain name of your {tekton-results} route. Replace `sha256~xyz` with the wuahtntication token that you generated.
+
+
+.Verification
+
+You can view the configuration that you set for the `opc` utility by entering the following command:
+
+[source,terminal]
+----
+$ opc results config view
+----
+
+.Example output of the `opc results config view` command
+[source]
+----
+api-path: ""
+apiVersion: results.tekton.dev/v1alpha2
+host: https://tekton-results.openshiftapps.com
+insecure-skip-tls-verify: "true"
+kind: Client
+token: sha256~xyz
+----
diff --git a/modules/op-results-opc-pipelinerunlist.adoc b/modules/op-results-opc-pipelinerunlist.adoc
@@ -0,0 +1,64 @@
+// This module is included in the following assembly:
+//
+// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="results-opc-pipelinerunlist_{context}"]
+= Viewing a list of pipeline run names and identifiers
+
+[role="_abstract"]
+You can use the `opc` utility to view a list of names and identifiers of pipeline runs in a namespace.
+
+
+.Prerequisites
+
+* You installed the `opc` utility.
+* You configured the `opc` utility to query results from {tekton-results} by pipeline run and task run names.
+
+.Procedure
+
+* Use any of the following commands to view pipeline runs:
+
+** To view all pipeline runs in a specified namespace, enter the following command:
++
+[source,terminal]
+----
+$ opc results pipelinerun list -n <namespace_name>
+----
++
+Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
++
+Optionally, specify the `--labels` command line option, for example, `--labels="app.kubernetes.io/name=test-app, app.kubernetes.io/component=database`. With this setting, the list includes only the pipeline runs that have the specified labels or annotations.
++
+.Example output of the `opc results pipelinerun list` command
++
+[source]
+----
+NAME                                           UID                                    STARTED      DURATION   STATUS
+openshift-pipelines-main-release-tests-zscq8   78515e3a-8e20-43e8-a064-d2442c2ae845   1 week ago   5s         Failed(CouldntGetPipeline)
+openshift-pipelines-main-release-tests-zrgv6   14226144-2d08-440d-a600-d602ca46cdf6   1 week ago   26m13s     Failed
+openshift-pipelines-main-release-tests-jdc24   e34daea2-66fb-4c7d-9d4b-d9d82a07b6cd   1 week ago   5s         Failed(CouldntGetPipeline)
+openshift-pipelines-main-release-tests-6zj7f   9b3e5d68-70ab-4c23-8872-e7ad7121e60b   1 week ago   5s         Failed(CouldntGetPipeline)
+openshift-pipelines-main-release-tests-kkk9t   2fd28c48-388b-4e6a-9ec3-2bcd9dedebc3   1 week ago   5s         Failed(CouldntGetPipeline)
+----
+
+** To view pipeline runs related to specified named pipelines, enter the following command:
++
+[source,terminal]
+----
+$ opc results pipelinerun list <pipeline_name> -n <namespace_name>
+----
++
+The command lists all pipeline runs for pipelines that have names containing `<pipeline_name>`. For example, if you specify `build`, the command displays all pipeline runs related to pipelines named `build`, `build_123`, or `enhancedbuild`.
++
+Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
+
+[NOTE]
+====
+If you do not specify the `-n` option, the `opc` command applies to the current namespace, To set the current namespace, use the `oc project` command.
+====
+
+[NOTE]
+====
+You can use the short form `opc results pr list` instead of `opc results pipelinerun list`.
+====
diff --git a/modules/op-results-opc-pipelinerunresults.adoc b/modules/op-results-opc-pipelinerunresults.adoc
@@ -0,0 +1,114 @@
+// This module is included in the following assembly:
+//
+// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="results-opc-pipelinerunresults_{context}"]
+= Viewing result information for a pipeline run
+
+[role="_abstract"]
+You can use the `opc` utility to view a description of when and how a pipeline run completed, a full manifest for the pipeline run, and any logs that the pipeline run produced.
+
+.Prerequisites
+
+* You installed the `opc` utility.
+* You configured the `opc` utility to query results from {tekton-results} by pipeline run and task run names.
+* You have the name or UUID of the pipeline run. You can use the `ocp results list pipelineruns` commands to view names and UUIDs of pipeline runs for which results are available.
+
+.Procedure
+
+* Use any of the following commands to view the result information for a pipeline run:
+** To view a description of when and how the pipeline run completed, enter the following command:
++
+[source,terminal]
+----
+$ opc results pipelinerun describe -n <namespace_name> <pipelinerun_name>
+----
++
+Alternatively, you can use the pipeline run UUID instead of the name:
++
+[source,terminal]
+----
+$ opc results pipelinerun describe -n <namespace_name> --uid <pipelinerun_uuid>
+----
++
+.Example output of the `opc results pipelinerun describe` command
+[source]
+----
+Name: operator-main-index-4-18-on-pull-request-7kssl
+Namespace: tekton-ecosystem-tenant
+Service Account: appstudio-pipeline
+Labels:
+ app.kubernetes.io/managed-by=pipelinesascode.tekton.dev
+ app.kubernetes.io/version=v0.33.0
+Annotations:
+ appstudio.openshift.io/snapshot=openshift-pipelines-main-b7jj6
+ build.appstudio.openshift.io/repo=https://github.com/openshift-pipelines/operator?rev=ba5e62e51af0c88bc6c3fd4201e789bdfc093daa
+
+📌 Status
+STARTED          DURATION         STATUS
+27d ago          9m54s            Succeeded
+
+⏱ Timeouts
+Pipeline:   2h0m0s
+
+⚓ Params
+  NAME                          VALUE
+  • git-url                     https://github.com/pramodbindal/operator
+  • revision                    ba5e62e51af0c88bc6c3fd4201e789bdfc093daa
+
+🗂  Workspaces
+  NAME                SUB PATH            WORKSPACE BINDING
+  • workspace          ---                VolumeClaimTemplate
+  • git-auth           ---                Secret (secret=pac-gitauth-ceqzjt)
+
+📦 Taskruns
+  NAME                                                                         TASK NAME
+  • operator-main-index-4-18-on-pull-request-7kssl-init                        init
+  • operator-main-index-4-18-on-pull-request-7kssl-clone-repository            clone-repository
+----
+
+* To view the full YAML manifest of the pipeline run, enter the following command:
++
+[source,terminal]
+----
+$ opc results pipelinerun describe -n <namespace_name> --output yaml <pipelinerun_name>
+----
++
+Alternatively, you can use the pipeline run UUID instead of the name:
++
+[source,terminal]
+----
+$ opc results pipelinerun describe -n <namespace_name> --output yaml --uid <pipelinerun_uuid>
+----
+
+* To view the logs associated with the pipeline run, enter the following command:
++
+[source,terminal]
+----
+$ opc results pipelinerun logs -n <namespace_name> <pipelinerun_name>
+----
++
+Alternatively, you can use the pipeline run UUID instead of the name:
++
+[source,terminal]
+----
+$ opc results pipelinerun logs -n <namespace_name> --uid <pipelinerun_uuid>
+----
+
+[IMPORTANT]
+====
+Logs that the `opc results pipelinerun logs` displays do not include logs of task runs that completed within this pipeline runs. To view these logs, find the names of the task runs in this pipeline run using the `opc results taskrun list --pipelinerun` command and specify the name of the pipeline run. Then use the `opc results taskrun log` command to view the logs for the task runs.
+====
+
+[NOTE]
+====
+If you do not specify the `-n` option, the `opc` command applies to the current namespace, To set the current namespace, use the `oc project` command.
+====
+
+[NOTE]
+====
+You can use the short form `opc results pr desc` instead of `opc results pipelinerun describe`.
+
+You can use the short form `opc results pr logs` instead of `opc results pipelinerun logs`.
+====
diff --git a/modules/op-results-opc-taskrunlist.adoc b/modules/op-results-opc-taskrunlist.adoc
@@ -0,0 +1,72 @@
+// This module is included in the following assembly:
+//
+// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="results-opc-taskrunlist_{context}"]
+= Viewing a list of task run names and identifiers
+
+[role="_abstract"]
+You can use the `opc` utility to view a lists of names and identifiers of task runs in a namespace or of task runs associated with a pipeline dun.
+
+
+.Prerequisites
+
+* You installed the `opc` utility.
+* You configured the `opc` utility to query results from {tekton-results} by pipeline run and task run names.
+
+.Procedure
+
+* To view a list of all task runs in a namespace, enter the following command:
++
+[source,terminal]
+----
+$ opc results taskrun list -n <namespace_name>
+----
++
+Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
++
+Optionally, specify the `--labels` parameter, for example, `--labels="app.kubernetes.io/name=test-app, app.kubernetes.io/component=database`. With this setting, the list includes only the task runs that have the specified labels or annotations.
++
+.Example output of the `opc results pipelinerun list` command for a namespace
++
+[source]
+----
+NAME                                           UID                                    STARTED      DURATION   STATUS
+openshift-pipelines-main-release-tests-zrgv6-e2e-test             10d6952f-b926-4e4b-a976-519867969ce7   16d ago   12m41s     Failed
+openshift-pipelines-main-release-tests-zrgv6-deploy-operator      ab41b63b-16ec-4a32-8b95-f2678eb5c945   16d ago   22s        Succeeded
+openshift-pipelines-main-release-tests-zrgv6-provision-cluster    b374df00-5132-4633-91df-3259670756b3   16d ago   12m30s     Succeeded
+operator-main-index-4-18-on-pull-request-ml4ww-show-sbom          c5b77784-cd87-4be8-bc12-28957762f382   16d ago   16s        Succeeded
+openshift-c4ae3a5a28e19ffc930e7c2aa758d85c-provision-eaas-space   22535d8e-d360-4143-9c0c-4bd0414a22b0   16d ago   17s        Succeeded
+----
+
+* To view a list of task runs associate with a pipeline run, enter the following command:
++
+[source,terminal]
+----
+$ opc results taskrun list --pipelinerun <pipelinerun_name> -n <namespace_name>
+----
++
+Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
+
+.Example output of the `opc results taskrun list` command for a pipeline run
++
+[source]
+----
+NAME                                                              UID                                    STARTED   DURATION   STATUS
+operator-main-index-4-18-on-pull-request-g95fk-show-sbom          5b405941-0d3e-4f8c-a68a-9ffcc481abf1   16d ago   13s        Succeeded
+operator-main-index-4-18-on-pul2b222db723593a186d12f1b82f1a1fd9   89588ae7-aa36-4b62-97d1-5634ee201850   16d ago   36s        Succeeded
+operator-fb80434867bc15d89fea82506058f664-fbc-fips-check-oci-ta   7598d44a-4370-459b-8ef0-ae4165c58ba5   16d ago   5m52s      Succeeded
+operator-main-index-4-18-on-pull-request-g95fk-validate-fbc       fb80d962-807b-4b63-80cb-6a57d383755a   16d ago   1m26s      Succeeded
+operator-main-index-4-18-on-pull-request-g95fk-apply-tags         8a34b46d-74a9-4f20-9e99-a285f7b258d6   16d ago   13s        Succeeded
+----
+
+[NOTE]
+====
+If you do not specify the `-n` option, the `opc` command applies to the current namespace, To set the current namespace, use the `oc project` command.
+====
+
+[NOTE]
+====
+You can use the short form `opc results tr list` instead of `opc results taskrun list`.
+====