diff --git a/docs/modules/ROOT/pages/how-tos/configuring/creating-secrets.adoc b/docs/modules/ROOT/pages/how-tos/configuring/creating-secrets.adoc
index 2eb415ec..39f6bc70 100644
--- a/docs/modules/ROOT/pages/how-tos/configuring/creating-secrets.adoc
+++ b/docs/modules/ROOT/pages/how-tos/configuring/creating-secrets.adoc
@@ -67,9 +67,54 @@ Using the PAT authentication requires only the `password` key. The `username` sh
 
 This secret will be used by the build service to perform both default and Pipeline-as-Code builds.
 
+
+It is also possible to have secrets for per-repository or organization access. To do this, a `appstudio.redhat.com/scm.repository` annotation should be added to the secret. It may either specify the full repository path or the partial path with a wildcard. For example, to create a secret for all repositories in the `my-user` organization, create (or add) the following YAML file:
+
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: pipelines-as-code-secret
+  namespace: <YOUR NAMESPACE>
+  labels:
+    appstudio.redhat.com/credentials: scm
+    appstudio.redhat.com/scm.host: <gitlab-host> # for example, gitlab.com
+  annotations:
+    appstudio.redhat.com/scm.repository: my-user/*
+type: kubernetes.io/basic-auth
+stringData:
+  password: <PERSONAL GITLAB ACCESS TOKEN>
+----
+
+For a specific repository, the following secret should be created:
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: pipelines-as-code-secret
+  namespace: <YOUR NAMESPACE>
+  labels:
+    appstudio.redhat.com/credentials: scm
+    appstudio.redhat.com/scm.host: <gitlab-host> # for example, gitlab.com
+  annotations:
+    appstudio.redhat.com/scm.repository: <repository-path> # for example, my-user/my-repo
+type: kubernetes.io/basic-auth
+stringData:
+  password: <PERSONAL GITLAB ACCESS TOKEN>
+----
+
+[NOTE]
+====
+You can have multiple repositories listed under the `appstudio.redhat.com/scm.repository` annotation. Separate repository names with commas when listing them. The secret will be used for all repositories that match the specified paths.
+====
+
 [IMPORTANT]
 ==== 
-* Each workspace can contain only one set of credentials for each Source Control Management (SCM) system, such as GitHub or GitLab. It means you can’t add two different tokens for a GitLab repository to a single workspace.
+* Secrets lookup mechanism is searching for the most specific secret first. The secret with a repository annotation will be used first if it matches the component repository path. In none found, then a lookup will try to find a secret with a wildcard, or just the host matching one.
 
 * If you upload a GitLab access token to a workspace, {ProductName} won’t use the global GitHub application when accessing GitHub repositories.
 ====