add guide on how to onboard private Git repositories, with examples. Link to new docs from FAQ and installation guide.

Signed-off-by: CS Jiang <christinesjiang@gmail.com>

docs/faq/index.md

@@ -167,6 +167,11 @@ The behavior of Kustomize used by the controller is currently configured as foll
     it runs `kustomize` locally or in CI with the same set of flags as
     the controller and validates the output using `kubeval`.
 
+## Git questions
+
+### How do I onboard a private Git repository? 
+For instructions on using private Git repositories, see [onboarding private repositories](onboarding-private-repositories.md).
+
 ## Helm questions
 
 ### How to debug "not ready" errors?

docs/guides/installation.md

@@ -447,6 +447,8 @@ flux create kustomization podinfo-default \
   --health-check-timeout=2m
 ```
 
+For instructions on using private Git repositories, see [onboarding private repositories](onboarding-private-repositories.md).
+
 You can register Helm repositories and create Helm releases:
 
 ```sh

docs/guides/onboarding-private-repo.md

@@ -0,0 +1,114 @@
+# Onboarding a Private Git Repository
+
+This guide walks you through the common use-case of onboarding a private GitRepository source.
+
+The below examples and instructions assume you are using GitHub, but the same 
+can apply for other providers and their support for access-token password auth.
+
+## Creating Per-Repo Deploy Keys
+For detailed instructions on setting up per-repo deploy keys using SOPS/SSH- or
+ token-based Git authentication, see [the documentation in our flux2-multi-tenancy example](https://github.com/fluxcd/flux2-multi-tenancy#onboard-tenants-with-private-repositories).
+
+## Sharing Token Auth Across Repos
+If you are managing a multi-tenant cluster with Flux, you can cut a Personal 
+Access Token with `repo` access from a GitHub service account and use that 
+token for authenticating multiple private GitRepository sources.
+
+The benefits of sharing a token across multiple tenants instead of using 
+per-repo deploy keys include:
+* Control access for all of Flux using GitHub's ACLs like Teams (composes well
+ if you're using Terraform to manage GitHub)
+* You only have to manage/create one secret per cluster/namespace instead of 
+per-repo.
+
+The tradeoff is that revocation of access with a shared token is less granular 
+than on a per-repo basis; you will have to manage access on the org/team/
+user-level. 
+
+### HTTP/S Basic Auth Token Access
+1. Log into a GitHub service account that has `admin` access to the repo you 
+are onboarding, and visit [settings/tokens](https://github.com/settings/tokens) 
+to generate a Personal Access Token with `repo` scope. 
+2. Bootstrap your cluster with the token. Note that we add the `--token-auth` 
+flag, which lets Flux know that it should use your `GITHUB_TOKEN` permanently 
+for auth in the cluster.
+If you already bootstrapped your cluster when getting started but did not add 
+this flag, it is fine to re-run the bootstrap command. 
+```sh
+export GITHUB_TOKEN=$GITHUB_TOKEN
+flux bootstrap github \
+  --owner=$GITHUB_USER \
+  --repository=fleet-infra \
+  --branch=main \
+  --path=./clusters/my-cluster \
+  --token-auth
+```
+3.  You can verify that Flux has saved your `GITHUB_TOKEN` for ongoing 
+authentication by checking the `flux-system` secret in the `flux-system` 
+namespace:
+```sh
+kubectl get secret flux-system -n flux-system -o yaml
+# You should see the `data.username` and `data.password` fields
+```
+4. When onboarding a new GitRepository that is private, make sure to use the 
+HTTP/S protocol in `spec.url` and reference the `flux-system` secret with your 
+creds in `spec.secretRef`. 
+
+#### CLI Example
+You can do this on the command-line like so:
+```sh
+flux create source git podinfo \
+    --url=https://github.com/my-org/my-private-repo \
+    --branch=master \
+    --secret-ref=flux-system
+```
+
+#### YAML Manifest Example
+If you are onboarding your source by checking in a YAML to your platform admin
+ repo, it should look like this:
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+    name: my-private-repo
+    namespace: flux-system
+spec:
+    interval: 1m
+    url: https://github.com/my-org/my-private-repo
+    # since we are using a private GitHub repo, the below 
+    # section is needed to tell Flux to use the GitHub token in the 
+    # flux-system Secret for HTTP/S basic auth when syncing
+    secretRef:
+        name: flux-system
+    ref:
+        branch: master
+```
+
+### Note on namespaces
+**Note** that if you wish to manage your tenant `GitRepository` sources as part of a namespace that is _not_ flux-system (e.g. the `apps` namespace, [as in the multi-tenancy example](https://github.com/fluxcd/flux2-multi-tenancy/blob/main/tenants/base/dev-team/sync.yaml#L5)), the private source will not be able to read from the `flux-system` Secret.
+
+You will have to manually create a Kubernetes Secret with the `data.username` and `data.password` fields in the namespace that you are creating your `GitRepository` sources in. To keep Secrets private, consider using [kubeseal](sealed-secrets.md).
+```sh
+# for GitRepository private sources stored in the `apps` namespace
+kubectl create secret generic repo-auth -n apps \
+	--from-literal=username=$GITHUB_USER \
+	--from-literal=password=$GITHUB_TOKEN
+```
+
+To get your sources to use the Secret, just reference it by name in the `GitRepository.spec.secretRef` field:
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+    name: my-private-repo
+    namespace: apps
+spec:
+    interval: 1m
+    url: https://github.com/my-org/my-private-repo
+    secretRef:
+        name: repo-auth
+    ref:
+        branch: master
+```
+
+