Refactor Bootstrap GitHub docs

Signed-off-by: Stefan Prodan <[email protected]>

content/en/flux/installation/bootstrap/github.md

@@ -1,77 +1,150 @@
 ---
 title: GitHub and GitHub Enterprise
 linkTitle: GitHub
-description: "How to bootstrap Flux with GitHub"
+description: "How to bootstrap Flux with GitHub and GitHub Enterprise"
 weight: 20
 ---
 
-The `bootstrap github` command creates a GitHub repository if one doesn't exist and
-commits the Flux components manifests to specified branch. Then it
-configures the target cluster to synchronize with that repository by
-setting up an SSH deploy key or by using token-based authentication.
+The [flux bootstrap github](/flux/cmd/flux_bootstrap_github/) command deploys the Flux controllers
+on a Kubernetes cluster and configures the controllers to sync the cluster state from a GitHub repository.
+Besides installing the controllers, the bootstrap command pushes the Flux manifests to the GitHub repository
+and configures Flux to update itself from Git.
 
-Generate a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
-(PAT) that can create repositories by checking all permissions under `repo`. If
-a pre-existing repository is to be used the PAT's user will require `admin`
-[permissions](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role)
-on the repository in order to create a deploy key.
+After running the bootstrap command, any operation on the cluster (including Flux upgrades)
+can be done via Git push, without the need to connect to the Kubernetes cluster.
 
-Export your GitHub personal access token as an environment variable:
+{{% alert color="danger" title="Required permissions" %}}
+To bootstrap Flux, the person running the command must have **cluster admin rights** for the target Kubernetes cluster.
+It is also required that the person running the command to be the **owner** of the GitHub repository,
+or to have admin rights of a GitHub organization.
+{{% /alert %}}
+
+## GitHub PAT 
+
+For accessing the GitHub API, the boostrap command requires a GitHub personal access token (PAT)
+with **admin permission**.
+
+The GitHub PAT can be exported as an environment variable:
 
 ```sh
-export GITHUB_TOKEN=<your-token>
+export GITHUB_TOKEN=<gh-token>
 ```
 
+If the `GITHUB_TOKEN` env var is not set, the bootstrap command will promote you to type it the token.
+
+You can also supply the token using a pipe e.g. `echo "<gh-token>" | flux bootstrap github`.
+
+## GitHub Personal Account
+
+If you want to bootstrap Flux for a repository owned by a personal account, you can generate a
+[GitHub PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
+that can create repositories by checking all permissions under `repo`.
+
+If you want to use an existing repository, the PAT's user must have `admin`
+[permissions](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role).
+
 Run the bootstrap for a repository on your personal GitHub account:
 
 ```sh
 flux bootstrap github \
+  --token-auth \
   --owner=my-github-username \
-  --repository=my-repository \
+  --repository=my-repository-name \
+  --branch=main \
   --path=clusters/my-cluster \
   --personal
 ```
 
-{{% alert color="info" title="Deploy key" %}}
-The bootstrap command creates an SSH key which it stores as a secret in the
-Kubernetes cluster. The key is also used to create a deploy key in the GitHub
-repository. The new deploy key will be linked to the personal access token used
-to authenticate. **Removing the personal access token will also remove the deploy key.**
+If the specified repository does not exist, Flux will create it for you as private. If you wish to create
+a public repository, set `--private=false`.
+
+When using `--token-auth`, the CLI and the Flux controllers running on the cluster will use the GitHub PAT
+to access the Git repository over HTTPS.
+
+{{% alert color="danger" title="PAT secret" %}}
+Note that the GitHub PAT is stored in the cluster as a **Kubernetes Secret** named `flux-system`
+inside the `flux-system` namespace. If you want to avoid storing your PAT in the cluster,
+please see how to configure [GitHub Deploy Keys](#github-deploy-keys).
 {{% /alert %}}
 
+## GitHub Organization
+
+If you want to bootstrap Flux for a repository owned by an GitHub organization,
+it is recommended to creat a dedicated user for Flux under your organization.
+
+Generate a GitHub PAT for the Flux user that can create repositories by checking all permissions under `repo`.
+
+If you want to use an existing repository, the Flux user must have `admin` permissions for that repository.
+
 Run the bootstrap for a repository owned by a GitHub organization:
 
 ```sh
 flux bootstrap github \
+  --token-auth \
   --owner=my-github-organization \
   --repository=my-repository \
-  --team=team1-slug \
-  --team=team2-slug \
+  --branch=main \
   --path=clusters/my-cluster
 ```
 
-When you specify a list of teams, those teams will be granted maintainer access to the repository.
+When creating a new repository, you can specify a list of GitHub teams with `--team=team1-slug,team2-slug`,
+those teams will be granted maintainer access to the repository.
+
+## GitHub Enterprise
 
 To run the bootstrap for a repository hosted on GitHub Enterprise, you have to specify your GitHub hostname:
 
 ```sh
 flux bootstrap github \
+  --token-auth \
   --hostname=my-github-enterprise.com \
-  --ssh-hostname=my-github-enterprise.com \
   --owner=my-github-organization \
   --repository=my-repository \
   --branch=main \
   --path=clusters/my-cluster
 ```
 
-If your GitHub Enterprise has SSH access disabled, you can use HTTPS and token authentication with:
+If you want use SSH and [GitHub deploy keys](#github-deploy-keys),
+set `--token-auth=false` and provide the SSH hostname with `--ssh-hostname=my-github-enterprise.com`.
 
-```sh
-flux bootstrap github \
-  --token-auth \
-  --hostname=my-github-enterprise.com \
-  --owner=my-github-organization \
-  --repository=my-repository \
-  --branch=main \
+## GitHub Deploy Keys
+
+If you want to bootstrap Flux using SSH instead of HTTP/S, you can set `--token-auth=false` and the Flux CLI
+will use the GitHub PAT to set a deploy key for your repository.
+
+When using SSH, the bootstrap command will generate a SSH private key. The private key is stored
+in the cluster as a Kubernetes secret named `flux-system` inside the `flux-system` namespace.
+
+The generated SSH key defaults to `ECDSA P-384`, to change the format use `--ssh-key-algorithm` and `--ssh-ecdsa-curve`.
+
+The SSH public key, is used to create a GitHub deploy key.
+The deploy key is linked to the personal access token used to authenticate.
+
+By default, the GitHub deploy key is set to read-only access.
+If you're using Flux image automation, you must give it write access with `--read-write-key=true`.
+
+{{% alert color="info" title="Deploy Key rotation" %}}
+Note that when the PAT is removed or when it expires, the GitHub deploy key will stop working.
+To regenerate the deploy key, delete the `flux-system` secret from the cluster and re-run
+the bootstrap command using a valid GitHub PAT.
+{{% /alert %}}
+
+## Bootstrap without a GitHub PAT
+
+For existing GitHub repositories, you can bootstrap Flux over SSH without using a GitHub PAT.
+
+To use a SSH key instead of a GitHub PAT, the command changes to `flux bootstrap git`:
+
+```shell
+flux bootstrap git \
+  --url=ssh://[email protected]/<org>/<repository> \
+  --branch=<my-branch> \
+  --private-key-file=<path/to/ssh/private.key> \
+  --password=<key-passphrase> \
   --path=clusters/my-cluster
 ```
+
+**Note** that you must generate a SSH private key and set the public key as a deploy key on GitHub in advance.
+
+For more information on how to use the `flux bootstrap git` command,
+please see the generic Git server [documentation](generic-git-server.md).