Flux bootstrap for GitHub
The 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.
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.
Required permissionsTo 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.
For accessing the GitHub API, the boostrap command requires a GitHub personal access token (PAT) with administration permissions.
The GitHub PAT can be exported as an environment variable:
GITHUB_TOKEN env var is not set, the bootstrap command will prompt 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
that can create repositories by checking all permissions under
If you want to use an existing repository, the PAT’s user must have
Run the bootstrap for a repository on your personal GitHub account:
flux bootstrap github \ --token-auth \ --owner=my-github-username \ --repository=my-repository-name \ --branch=main \ --path=clusters/my-cluster \ --personal
If the specified repository does not exist, Flux will create it for you as private. If you wish to create
a public repository, set
--token-auth, the CLI and the Flux controllers running on the cluster will use the GitHub PAT
to access the Git repository over HTTPS.
PAT secretNote that the GitHub PAT is stored in the cluster as a Kubernetes Secret named
flux-systemnamespace. If you want to avoid storing your PAT in the cluster, please see how to configure GitHub Deploy Keys.
If you want to bootstrap Flux for a repository owned by an GitHub organization, it is recommended to create 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
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:
flux bootstrap github \ --token-auth \ --owner=my-github-organization \ --repository=my-repository \ --branch=main \ --path=clusters/my-cluster
When creating a new repository, you can specify a list of GitHub teams with
those teams will be granted maintainer access to the repository.
To run the bootstrap for a repository hosted on GitHub Enterprise, you have to specify your GitHub hostname:
flux bootstrap github \ --token-auth \ --hostname=my-github-enterprise.com \ --owner=my-github-organization \ --repository=my-repository \ --branch=main \ --path=clusters/my-cluster
If you want use SSH and
GitHub deploy keys,
--token-auth=false and provide the SSH hostname with
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
The generated SSH key defaults to
ECDSA P-384, to change the format use
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
Deploy Key rotationNote 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-systemsecret from the cluster and re-run the bootstrap command using a valid GitHub PAT.
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:
flux bootstrap git \ --url=ssh://email@example.com/<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