Update documentation for ingresses and running PRs

This commit updates documentation for ingresses:
- to provide GKE examples
- to point to proxying docs
- to clarify where to find more information on setting up your ingress

It also clarifies where PipelineRun configuration must be stored,
and how PipelineRuns from pull requests can be run.

Author: lbernick

.vale.ini

@@ -22,6 +22,7 @@ IgnoredScopes = code, tt, img, url, a, body.id
 SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock
 
 RedHat.ConfigMap = NO
+RedHat.CaseSensitiveTerms = NO
 # Match Markdown files. See: https://docs.errata.ai/vale/scoping
 # Match also `*.properties` files (see the `format` section).
 [*.md]

docs/content/docs/guide/authoringprs.md

@@ -8,6 +8,12 @@ weight: 3
   possible. Usually you will write your template and save them with a `.yaml`
   extension and Pipelines as Code will run them.
 
+* The `.tekton` directory must be at the top level of the repo.
+  You can reference YAML files in other repos using remote URLs
+  (see [Remote HTTP URLs](./resolver.md#remote-http-url) for more information),
+  but PipelineRuns will only be triggered by events in the repository containing
+  the `.tekton` directory.
+
 * Using its [resolver](./resolver) Pipelines as Code will try to bundle the
   PipelineRun with all its Task as a single PipelineRun with no external
   dependencies.

docs/content/docs/guide/running.md

@@ -4,23 +4,24 @@ weight: 4
 ---
 # Running the PipelineRun
 
-The user flow looks like this :
+Pipelines as Code will run any PipelineRuns committed to the default branch of the repo
+when the specified events occur on the repo.
+For example, if a PipelineRun on the default branch has the annotation
+`pipelinesascode.tekton.dev/on-event: "[pull_request]"`, it will run whenever a pull request event occurs.
 
-- A user create a `Pull Request` (or `Merge Request` in Gitlab).
+Pipelines as Code will also run any PipelineRuns from a branch in a pull request (or merge request in Gitlab).
+For example, if you're testing out a new PipelineRun, you can create a pull request
+with that PipelineRun, and it will run if the following conditions are met:
 
-- Pipelines as Code picks the event and matches to a Repo CRD installed on the
-  cluster.
+- The pull request author's PipelineRun will be run if:
 
-- The user is allowed to run the CI if :
-
-  - The user is the owner of the repository.
-  - The user is a collaborator on the repository.
-  - The user is a public member on the organization of the repository.
-
-- If the user is sending the Pull Request is inside an OWNER file located in the
+  - The author is the owner of the repository.
+  - The author is a collaborator on the repository.
+  - The author is a public member on the organization of the repository.
+  - The pull request author is inside an OWNER file located in the
   repository root on the main branch (the main branch as defined in the GitHub
   configuration for the repo) and added to either `approvers` or `reviewers`
-  sections like this :
+  sections. For example, if the approvers section looks like this:
 
 ```yaml
 approvers:
@@ -29,13 +30,16 @@ approvers:
 
 then the user `approved` will be allowed.
 
-- If the sender of a PR is not allowed to run CI but one of allowed user issue a
-  `/ok-to-test` in any line of a comment the PR will be allowed to run CI.
+If the pull request author does not meet these requirements,
+another user that does meet these requirements can comment `/ok-to-test` on the pull request
+to run the PipelineRun.
+
+## PipelineRun Execution
 
-- If the user is allowed, `Pipelines as Code` will start creating the
-`PipelineRun` in the target user namespace.
+The PipelineRun will always run in the namespace of the Repository CRD associated with the repo
+that generated the event.
 
-- The user can follow the execution of your pipeline with the
+You can follow the execution of your pipeline with the
 [tkn](https://github.com/tektoncd/cli) cli :
 
 ```console
@@ -55,7 +59,7 @@ your branch or pull_request.
 
 On GitHub if you are using the Github apps, you can go to the Checks tab and
 click on the upper left button called "Re-Run" and Pipelines as Code will react
-to the event and restart testing the PipelineRun
+to the event and restart testing the PipelineRun.
 
 ### Gitops command on pull or merge request
 

docs/content/docs/install/github_apps.md

@@ -19,8 +19,9 @@ There are 2 ways to set up GitHub App:
 
 You could use [`tkn pac bootstrap`](/docs/guide/cli) command which will a create GitHub App, provides
 steps to configure it with your Git repository and also creates required secrets.
+After creating the Github App, you must install it on the repositories you want to use for Pipelines as Code.
 
-Alternatively, you could set up manually by following the steps [here](#setup-manually)
+Alternatively, you could set up manually by following the steps [here](#setup-manually).
 
 ## Setup Manually
 
@@ -61,7 +62,7 @@ Alternatively, you could set up manually by following the steps [here](#setup-ma
   download automatically. Store the private key in a safe place as you need it in the next section and in future when
   reconfiguring this app to use a different cluster.
 
-## Configure Pipelines-as-Code on your cluster to access the GitHub App
+### Configure Pipelines-as-Code on your cluster to access the GitHub App
 
 In order for Pipelines-as-Code to be able to authenticate to the GitHub App and have the GitHub App securely trigger the
 Pipelines-as-Code webhook, you need to create a Kubernetes secret containing the private key of the GitHub App and the
@@ -86,6 +87,8 @@ kubectl -n pipelines-as-code create secret generic pipelines-as-code-secret \
         --from-literal webhook.secret="WEBHOOK_SECRET"
 ```
 
+Lastly, install the App on any repos you'd like to use with Pipelines as Code.
+
 ## GitHub Enterprise
 
 Pipelines as Code supports GitHub Enterprise.

docs/content/docs/install/installation.md

@@ -140,19 +140,13 @@ You can use following command to update the envs on the controller
 
 ## Proxy service for PAC controller
 
-### What
+Pipelines as Code requires an externally accessible URL to receive events from Git providers.
+If you're developing locally (such as on kind or Minikube) or don't want to set up an ingress on your cluster,
+you can also use a proxy service to expose the `pipelines-as-code-controller` service and allow it to receive events.
 
-proxy service is used to forward request coming to `pipelines-as-code-controller` service
+### Proxying with smee.io
 
-### Why
-
-PAC requires externally accessible URL to configure for GitHub, GitLab, BitBucket and there are few clusters which doesn't expose services to external world ex: Minikube, Kind and so on.
-
-### Proposed solution
-
-To handle such scenario for minikube/kind cluster lets use [smee.io](https://smee.io/)
-
-### Steps to configure smee.io
+To handle such scenario for minikube/kind cluster let's use [smee.io](https://smee.io/)
 
 - Generate your own URL by going to [smee.io/new](https://smee.io/new)
 - Copy `Webhook Proxy URL`

docs/content/docs/install/kubernetes.md

@@ -25,9 +25,28 @@ and for the nightly :
 kubectl apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/nightly/release.k8s.yaml
 ```
 
+## Verify
+
+Ensure that the pipelines-as-code controller, webhook, and watcher have come up healthy, for example:
+
+```shell
+$ kubectl get deployment -n pipelines-as-code
+NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
+pipelines-as-code-controller   1/1     1            1           43h
+pipelines-as-code-watcher      1/1     1            1           43h
+pipelines-as-code-webhook      1/1     1            1           43h
+```
+
+All three deployments should have all pods ready before moving on to ingress setup.
+
 ## Ingress
 
-You will need a `Ingress` to point to the pipelines-as-code controller, here is an example working with the [nginx ingress](https://kubernetes.github.io/ingress-nginx/) controller :
+You will need a `Ingress` to point to the pipelines-as-code controller.
+The ingress configuration depends on your Kubernetes provider.
+Either the ingress hostname or its IP address may be used as the webhook URL.
+You'll provide this configuration when connecting Pipelines as Code to your Git provider.
+
+Here is an example working with the [nginx ingress](https://kubernetes.github.io/ingress-nginx/) controller :
 
 ```yaml
 apiVersion: networking.k8s.io/v1
@@ -52,7 +71,34 @@ spec:
         pathType: Prefix
 ```
 
-In this example `webhook.host.tld` is the hostname for your pipeline's controller to fill as the webhook URL in the provider platform setup.
+In this example `webhook.host.tld` is the hostname that will be used for the Pipelines as Code webhook URL.
+
+Here's an example with GKE:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  labels:
+    pipelines-as-code/route: controller
+  name: pipelines-as-code
+  namespace: pipelines-as-code
+  annotations:
+    kubernetes.io/ingress.class: gce
+spec:
+  defaultBackend:
+    service:
+      name: pipelines-as-code-controller
+      port:
+        number: 8080
+```
+
+In this example, you will use the ingress's IP address rather than a hostname for the webhook URL.
+You can find the ingress's address via `kubectl get ingress pipelines-as-code -n pipelines-as-code`.
+
+If you can't or don't want to set up an ingress on your cluster (for example, you're using a kind cluster,
+or you just want to experiment with Pipelines as Code before setting up an ingress),
+see [Proxy service for PAC controller](./installation.md#proxy-service-for-pac-controller).
 
 ## Tekton Dashboard integration