Merge pull request #208 from kasemAlem/KONFLUX-5917

fix(Konflux 5917):  add an example how user can use a secret in pipeline

Author: arewm

docs/modules/ROOT/pages/how-tos/configuring/creating-secrets.adoc

@@ -12,7 +12,7 @@ Secrets can be categorized depending on when they need to be added.
 
 Sometimes to run the tasks properly, you may need to pass secrets to these tasks. Consult the documentation for these tasks to understand the proper specification of the secrets required, for example the required keys/values.
 
-NOTE: One such task is the link:https://github.com/konflux-ci/build-definitions/tree/main/task/sast-snyk-check[sast-snyk-check] task that uses the third-party service link:https://snyk.io/[snyk] to perform static application security testing (SAST) as a part of the default {ProductName} pipeline. Use this procedure to upload your snyk.io token. Name the secret `snyk-secret` so that the snyk task in the {ProductName} pipeline will recognize it and use it.
+NOTE: One such task is the link:https://github.com/konflux-ci/build-definitions/tree/main/task/sast-snyk-check[sast-snyk-check] task that uses the third-party service link:https://snyk.io/[snyk] to perform static application security testing (SAST) as a part of the default {ProductName} pipeline. Use this procedure to upload your snyk.io token. Name the secret `sast_snyk_task` so that the snyk task in the {ProductName} pipeline will recognize it and use it.
 
 .Procedure 
 
@@ -54,15 +54,56 @@ Some container builds may use parent images from registries that require authent
 . Enter the password for the registry in **Password**.
 . Click **Add secret**.
 
+=== Example of creating a quay.io secret
+
+. Login to {ProductName} console your workspace (https://console.redhat.com/application-pipeline/workspaces/<your workspace>/applications)
+. Click on `Secrets` on the left menu.
+. Click on `Add Secret`
+. Choose `Image pull secret` for `Secret type`
+. Enter `Secret name` , for example `my-quay-secret` 
+. Choose `Image registry credentials` in `Authentication type` field
+. Enter `quay.io` in `Registry server address`
+. Enter your Quay.io username in `Username`
+. Enter your Quay.io API token in `Password` field.
+. Click on `Add secret`
+. Email is optional
+
+
+Here is the YAML representation of the secret (for reference):
+
+[source,yaml]
+----
+apiVersion: v1
+data:
+.dockerconfigjson: <base64-encoded-credentials>
+kind: Secret
+metadata:
+name: my-quay-secret
+namespace: <your-workspace-tenant>
+type: kubernetes.io/dockerconfigjson
+----
+
 
 [NOTE]
 ====
-Performing this operation through the UI will link the secret to the `appstudio-pipeline`
-`serviceaccount` automatically. If you instead wanted to add manually the secret to the
-namespace (creating the `secret` directly on the tenant
-workspace), you'll need to have the secret linked manually.
-
-please review the xref:/troubleshooting/index.adoc#check-if-the-secret-is-linked-to-the-service-account[troubleshooting section]) for more info.
+* **Automatic Secret Linking via UI**  
+  The {ProductName} UI automatically links image pull secrets to the `appstudio-pipeline` ServiceAccount.  
+  - No pipeline YAML changes are required.  
+  - Tasks like the buildah task will use this secret automatically when pulling images from `quay.io`. (https://github.com/konflux-ci/build-definitions/blob/main/task/buildah-oci-ta/0.3/buildah-oci-ta.yaml in volumes) 
+
+* **Manual Secret Creation**  
+  . **Link Secret To SA** 
+    - If you create the secret manually (e.g., via `kubectl` or YAML), you must **manually link it** to the `appstudio-pipeline` ServiceAccount in your namespace.
+  . **Secrets Via Workspace** 
+    - Explicitly mount secrets as files using a workspace
+    - RBAC: Ensure the ServiceAccount has permission to access the secret (via Role/RoleBinding).
+
+  . **Secrets as Environment Variables** 
+    - Inject secrets into environment variables
+    - RBAC: The ServiceAccount must have `get` permission for the secret.
+
+* **Troubleshooting**  
+  For issues with secret linking, review the xref:/troubleshooting/index.adoc#check-if-the-secret-is-linked-to-the-service-account[troubleshooting section].
 ====
 
 == Creating source control secrets
@@ -171,4 +212,4 @@ stringData:
 
 * For more information about GitLab access tokens, see link:https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html[Project access tokens].
 
-* To configure push secrets for your Build and Release pipelines, see link:https://github.com/konflux-ci/konflux-ci?tab=readme-ov-file#configuring-a-push-secret-for-the-build-pipeline[Configuring push secrets] in the Konflux GitHub repository.
+* To configure push secrets for your Build and Release pipelines, see link:https://github.com/konflux-ci/konflux-ci?tab=readme-ov-file#configuring-a-push-secret-for-the-build-pipeline[Configuring push secrets] in the Konflux GitHub repository.