docs: document repository auth modes

docs/content/5_workload_onboarding/add_app_repository.md

@@ -7,34 +7,104 @@ For more information check:
 https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/
 
 ## **Add credentials to vault**
-Add the repository credentials to your vault at
-`<cluster-name>/<stage>/repo_pat`. This can be a `password` or a `PAT`.
+Add the repository credentials to your vault below `<cluster-name>/<stage>`.
+The examples below use one secret value per repository credential.
+
+For HTTPS username + password/PAT authentication, `PAT` usually means Personal Access Token and is often tied to a user account.
+For platform automation, prefer a technical or machine account instead of a personal user account.
+Set `username` to the account name expected by your Git provider; the exact value is provider-dependent.
+
 ```json
 {
   "repo_pat": {
-    "pat": "<the kubeconfig>"
+    "pat": "<password-or-PAT>"
+  }
+}
+```
+
+For SSH deploy key authentication:
+
+```json
+{
+  "repo_ssh": {
+    "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----"
+  }
+}
+```
+
+For GitHub App authentication:
+
+```json
+{
+  "repo_github_app": {
+    "privateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
   }
 }
 ```
+
 ## **Modify Argo CD overlays**
-Add the following to your Argo CD overlay, typically `platform-configs/<hub-cluster-name>/helm/argo-cd/values-additional.yaml`.
+Add one of the following repository definitions to your Argo CD overlay, typically
+`platform-configs/<hub-cluster-name>/helm/argo-cd/values-additional.yaml`.
+
+HTTPS username + password/PAT:
+
+```yaml
+repositories:
+  - name: user-repo-mock
+    authMode: https
+    projectScope: k8s-spoke-0
+    remoteRef:
+      remoteKey: <cluster-name>/<stage>/repo_pat
+      remoteKeyProperty: pat
+    repoType: git
+    secretStoreRef:
+      kind: ClusterSecretStore
+      name: hub-0-production
+    url: https://git.example.com/org/repo.git
+    username: <technical-account-username>
+```
+
+SSH deploy key:
+
 ```yaml
 repositories:
-    - name: user-repo-mock
-      projectScope: k8s-spoke-0
-      # # This points to the secret in vault
-      remoteRef:
-        remoteKey: <cluster-name>/<stage>/repo_pat
-        remoteKeyProperty: pat
-      repoType: git
-      secretStoreRef:
-        kind: ClusterSecretStore
-        name: hub-0-production
-      url: <the repo url you want to add>
-      username: <the username for connection. also needed for PAT>
+  - name: user-repo-ssh
+    authMode: ssh
+    projectScope: k8s-spoke-0
+    sshPrivateKeyRemoteRef:
+      remoteKey: <cluster-name>/<stage>/repo_ssh
+      remoteKeyProperty: privateKey
+    repoType: git
+    secretStoreRef:
+      kind: ClusterSecretStore
+      name: hub-0-production
+    url: git@git.example.com:org/repo.git
 ```
 
-That whats happening behind the scenes:
+For SSH repositories, make sure Argo CD already trusts the SSH host key. See the bootstrap documentation for `configs.ssh.extraHosts`.
+
+GitHub App:
+
+```yaml
+repositories:
+  - name: user-repo-github-app
+    authMode: github-app
+    projectScope: k8s-spoke-0
+    githubAppID: "123456"
+    githubAppInstallationID: "987654"
+    githubAppPrivateKeyRemoteRef:
+      remoteKey: <cluster-name>/<stage>/repo_github_app
+      remoteKeyProperty: privateKey
+    repoType: git
+    secretStoreRef:
+      kind: ClusterSecretStore
+      name: hub-0-production
+    url: https://github.com/org/repo.git
+```
+
+For GitHub Enterprise, also set `githubAppEnterpriseBaseUrl`.
+
+That's what's happening behind the scenes:
 
 ![Add Repository](../images/add-repository.png)