Merge pull request #134 from gtrivedi88/docs/fix-quay-link

Address SME feedback across all documentation pages

Author: Roming22

docs/modules/ROOT/pages/getting-started.adoc

@@ -51,11 +51,18 @@ For more details, see link:https://konflux-ci.dev/docs/building/creating/#with-t
 
 After you create a component, {KonfluxName} automatically:
 
-. **Sends a pull request** to your Git repository. This PR adds a build pipeline definition (`.tekton/` directory) that triggers on pull request and push events targeting the onboarded branch.
+. **Sends a pull request** to your Git repository. This PR adds Tekton pipeline definitions (`.tekton/` directory) that trigger on pull request and push events targeting the onboarded branch. Those pipelines control the lifecycle of changes submitted to the repository.
 
-. **Configures a default integration test pipeline.** This pipeline runs automatically after each build to evaluate the artifacts against the configured policy. The integration test definition is stored as a Custom Resource in OpenShift and is not visible in your Git repository.
+. **Configures a default integration test pipeline.** This pipeline runs automatically after each build to evaluate the artifacts against the configured policy. The integration test definition is stored as a Custom Resource in {OCPShortName} and is not visible in your Git repository.
++
+To view the integration test Custom Resource:
++
+[source,bash]
+----
+oc get integrationtestscenarios -n <tenant-namespace>
+----
 
-. **Creates CI checks** on the pull request (GitHub checks or GitLab webhooks, depending on your Git provider). Two checks appear:
+. **Creates CI checks** on the pull request. {KonfluxName} creates checks for both GitHub and GitLab. The difference is how the integration with {KonfluxName} is managed: for GitHub, a GitHub App is created ahead of time during installation; for GitLab, the webhook is created when the repository is onboarded. Two checks appear:
 * One for the build pipeline status
 * One for the integration test pipeline status
 +

docs/modules/ROOT/pages/installing.adoc

@@ -21,7 +21,7 @@ Start the {TSFShortName} installer container using Podman. The installer runs in
 ----
 podman run -it --rm --env-file tsf.env \
   --entrypoint bash -p 8228:8228 --pull always \
-  {TSFInstallerImage} --login
+  quay.io/redhat-ads/tsf-cli:unstable --login
 ----
 +
 This command pulls the latest installer image and opens an interactive shell session inside the container. The `--login` flag sources the shell profile, and port 8228 is exposed for the GitHub App creation workflow.
@@ -93,6 +93,8 @@ products:
 
 NOTE: The {TSFShortName} installer assumes a fresh cluster. If other {TSFShortName}-managed operators are already installed (such as Red Hat OpenShift Pipelines or {RHTASName}), set `manageSubscription: false` for each pre-installed component to prevent conflicts.
 
+The `tsf-config` ConfigMap in the `tsf` namespace controls which components are installed. Each component has an `enabled` flag and a `manageSubscription` property. Set `manageSubscription` to `false` for any component that is already installed on the cluster.
+
 === Verification
 
 Verify that the ConfigMap was created:
@@ -104,6 +106,13 @@ oc get configmap tsf-config -n tsf
 
 The output shows the `tsf-config` ConfigMap in the `tsf` namespace.
 
+To view the complete ConfigMap structure:
+
+[source,bash]
+----
+oc get configmap tsf-config -n tsf -o yaml
+----
+
 == Configure the GitHub integration
 
 Create and install a GitHub App that enables {TSFShortName} to interact with your GitHub repositories. The GitHub App provides webhooks for triggering builds and access to repository contents.
@@ -175,11 +184,11 @@ If you are using GitLab instead of GitHub, configure the GitLab integration. Cre
 ----
 oc create secret generic gitlab-auth-secret \
   -n <tenant-namespace> \
-  --from-literal=password=<project-access-token> \
+  --from-literal=password="$GITLAB__TOKEN" \
   --type=kubernetes.io/basic-auth
 ----
 +
-Replace `<tenant-namespace>` with your tenant namespace and `<project-access-token>` with the token you copied.
+The default tenant namespace is `default-tenant`. If multiple namespaces are used, the secret must be created in each namespace where you onboard components. For more information about tenant namespaces, see link:https://konflux-ci.dev/docs/advanced-how-tos/managing/environments/[Managing environments] in the {KonfluxName} documentation.
 
 . Label the secret so that {KonfluxName} can discover it:
 +
@@ -196,10 +205,8 @@ oc label secret gitlab-auth-secret \
 ----
 oc annotate secret gitlab-auth-secret \
   -n <tenant-namespace> \
-  appstudio.redhat.com/scm.host=gitlab.com
+  appstudio.redhat.com/scm.host="$GITLAB__HOST"
 ----
-+
-Replace `gitlab.com` with the hostname of your GitLab instance if you are using a self-hosted instance.
 
 === Verification
 

docs/modules/ROOT/pages/preparing-to-install.adoc

@@ -50,18 +50,20 @@ Create a Quay organization and generate an OAuth token. The {TSFShortName} insta
 
 Follow the Quay documentation to complete these steps:
 
-. link:https://docs.quay.io/guides/create-org.html[Create an organization] in your Quay registry.
-. link:https://docs.quay.io/api/[Create an OAuth application] within the organization and generate an access token with all permission scopes.
+. link:https://docs.quay.io/glossary/organizations.html[Create an organization] in your Quay registry.
+. link:https://docs.quay.io/glossary/access-token.html[Create an OAuth access token] within the organization and generate an access token with all permission scopes.
 
 Copy the access token and save it securely. Use this token in the next step when preparing the environment file.
 
 == Prepare the environment file
 
-Create an environment file that contains the credentials and configuration for your {OCPShortName} cluster, GitHub organization, and Quay registry. The {TSFShortName} installer reads this file to configure all integrations.
+Create an environment file that contains the credentials and configuration for your {OCPShortName} cluster, Git provider, and Quay registry. The {TSFShortName} installer reads this file to configure all integrations.
 
 === Steps
 
-. Create a file named `tsf.env` in your working directory with the following content:
+. Create a file named `tsf.env` in your working directory. Include the variables for your Git provider (GitHub or GitLab), along with the {OCPShortName} and Quay variables.
++
+If you are using **GitHub**:
 +
 [source,bash]
 ----
@@ -73,6 +75,26 @@ OCP__API_ENDPOINT=<your_cluster_api_url>
 OCP__USERNAME=<your_cluster_admin_username>
 OCP__PASSWORD=<your_cluster_admin_password>
 
+# Quay registry
+QUAY__API_TOKEN=<your_quay_oauth_token>
+QUAY__ORG=<your_quay_organization>
+QUAY__URL=<your_quay_url>
+----
++
+If you are using **GitLab**:
++
+[source,bash]
+----
+# gitlab.com
+GITLAB__HOST=gitlab.com
+GITLAB__GROUP=<your_gitlab_group>
+GITLAB__TOKEN=glpat-xxxx
+
+# OpenShift
+OCP__API_ENDPOINT=<your_cluster_api_url>
+OCP__USERNAME=<your_cluster_admin_username>
+OCP__PASSWORD=<your_cluster_admin_password>
+
 # Quay registry
 QUAY__API_TOKEN=<your_quay_oauth_token>
 QUAY__ORG=<your_quay_organization>
@@ -85,9 +107,24 @@ QUAY__URL=<your_quay_url>
 |===
 | Variable | Description
 
+2+h| GitHub
+
 | `GITHUB__ORG`
 | The name of the GitHub organization to use with {TSFShortName}.
 
+2+h| GitLab
+
+| `GITLAB__HOST`
+| The hostname of your GitLab instance. For example: `gitlab.com`. Replace with your self-hosted instance hostname if applicable.
+
+| `GITLAB__GROUP`
+| The name of the GitLab group that contains the projects to onboard.
+
+| `GITLAB__TOKEN`
+| A GitLab Project Access Token with the *Maintainer* role and `api`, `read_repository`, `write_repository` scopes.
+
+2+h| OpenShift
+
 | `OCP__API_ENDPOINT`
 | The full URL of the {OCPShortName} cluster API endpoint. For example: `\https://api.example.com:6443`.
 
@@ -97,6 +134,8 @@ QUAY__URL=<your_quay_url>
 | `OCP__PASSWORD`
 | The password for the cluster administrator user.
 
+2+h| Quay registry
+
 | `QUAY__API_TOKEN`
 | The OAuth token you generated for your Quay organization.
 

docs/modules/ROOT/pages/troubleshooting.adoc

@@ -1,7 +1,17 @@
 = Troubleshooting {TSFShortName} installation
+:toc:
 
 Use this guide to diagnose and resolve common issues during {TSFShortName} installation and deployment.
 
+**On this page:**
+
+* <<quay-token-error-during-deployment>>
+* <<cert-manager-subscription-conflict>>
+* <<rhtpa-ui-url-is-not-accessible>>
+* <<deployment-appears-to-hang>>
+* <<browser-fails-to-open-during-github-integration>>
+
+[id="quay-token-error-during-deployment"]
 == Quay token error during deployment
 
 **Symptom:** The `{TSFCli} deploy` command fails at the `tsf-konflux` chart with:
@@ -40,6 +50,7 @@ tsf integration quay \
 tsf deploy
 ----
 
+[id="cert-manager-subscription-conflict"]
 == Cert-Manager subscription conflict
 
 **Symptom:** The deployment fails with a subscription conflict error for the Cert-Manager operator.
@@ -55,6 +66,7 @@ oc edit configmap tsf-config -n tsf
 
 Locate the Cert-Manager entry and change `manageSubscription: true` to `manageSubscription: false`. Then re-run the deployment.
 
+[id="rhtpa-ui-url-is-not-accessible"]
 == {RHTPAName} UI URL is not accessible
 
 **Symptom:** The RHTPA UI URL displayed in the deployment output shows `server%s(<nil>)` or returns an error.
@@ -91,6 +103,7 @@ oc logs -n tsf-tpa deployment/rhtpa-operator
 oc get routes -n tsf-tpa
 ----
 
+[id="deployment-appears-to-hang"]
 == Deployment appears to hang
 
 **Symptom:** The `{TSFCli} deploy` command runs for an extended period without producing any output.
@@ -106,6 +119,7 @@ oc get pods -A --watch
 
 Wait for the deployment to complete. The full process typically takes about 15 minutes.
 
+[id="browser-fails-to-open-during-github-integration"]
 == Browser fails to open during GitHub integration
 
 **Symptom:** The `{TSFCli} integration github --create` command logs an error:

docs/modules/ROOT/pages/verifying-and-accessing.adoc

@@ -90,15 +90,6 @@ The installer also creates the following supporting namespaces:
 * `rhbk-operator`
 * `rhtpa-operator`
 
-The `tsf-config` ConfigMap in the `tsf` namespace controls which components are installed. Each component has an `enabled` flag and a `manageSubscription` property. Set `manageSubscription` to `false` for any component that is already installed on the cluster.
-
-To view the complete ConfigMap structure:
-
-[source,bash]
-----
-oc get configmap tsf-config -n tsf -o yaml
-----
-
 == Next step
 
 Proceed to xref:getting-started.adoc[Getting started with {TSFShortName}] to onboard your first application.