---
title: Flux bootstrap for Git servers
linkTitle: Generic Git server
description: "How to bootstrap Flux with a generic Git server"
weight: 20
---

The [flux bootstrap git](/flux/cmd/flux_bootstrap_git/) command deploys the Flux controllers
on a Kubernetes cluster and configures the controllers to sync the cluster state from a Git repository.
Besides installing the controllers, the bootstrap command pushes the Flux manifests to the Git 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.

{{% 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 has **push rights** to the Git repository.
{{% /alert %}}

## SSH Private Key

Run bootstrap for an existing Git repository and authenticate with a SSH key which has pull and push access:

```sh
flux bootstrap git \
  --url=ssh://git@<host>/<org>/<repository> \
  --branch=main \
  --private-key-file=<path/to/private.key> \
  --password=<key-passphrase> \
  --path=clusters/my-cluster
```

The private key is stored in the cluster as a Kubernetes secret named `flux-system`
inside the `flux-system` namespace.

{{% alert color="info" title="SSH Key rotation" %}}
To regenerate the SSH private key and known hosts keys,
delete the `flux-system` secret from the cluster and run:

```shell
flux create secret git flux-system \
  --url=ssh://git@<host>/<org>/<repository> \
  --private-key-file=<path/to/private.key> \
  --password=<key-passphrase>
```
{{% /alert %}}

## SSH Agent

Run bootstrap for an existing Git repository and authenticate with your SSH agent:

```sh
flux bootstrap git \
  --url=ssh://git@<host>/<org>/<repository> \
  --branch=main \
  --path=clusters/my-cluster
```

{{% alert color="warning" title="SSH hostname" %}}
If the Flux controllers must connect to a different SSH endpoint
than the CLI, you can set the SSH hostname and port for the cluster
with `--ssh-hostname=<host:port>`.
Note that if set, your SSH hostname and port could be overwritten by
your [ssh_config](https://linux.die.net/man/5/ssh_config).
{{% /alert %}}

When using the SSH Agent, the bootstrap command will generate a new SSH private key for the cluster, 
and it will prompt you to add the SSH public key as a deploy key to your repository.

The generated SSH key defaults to `ECDSA P-384`, to change the format use `--ssh-key-algorithm` and `--ssh-ecdsa-curve`.

{{% alert color="info" title="SSH Key rotation" %}}
To regenerate the SSH private key and known hosts keys,
delete the `flux-system` secret from the cluster and run:

```shell
flux create secret git flux-system \
  --url=ssh://git@<host>/<org>/<repository> \
  --ssh-key-algorithm=ecdsa \
  --ssh-ecdsa-curve=p384
```

The CLI will prompt you to add the SSH public key as a deploy key to your repository.
{{% /alert %}}

## HTTPS basic auth

If your Git server has basic auth enabled, you can bootstrap Flux over HTTPS with:

```sh
flux bootstrap git \
  --url=https://<host>/<org>/<repository> \
  --username=<my-username> \
  --password=<my-password> \
  --token-auth=true \
  --path=clusters/my-cluster
```

You can also supply the password or Git token using a pipe e.g. `echo "<my-pass>" | flux bootstrap git`.

If your Git server uses a self-signed TLS certificate, you can specify the CA file with
`--ca-file=<path/to/ca.crt>`.

## HTTPS authorization header

To access Git repositories that require a bearer token in the HTTP headers
as an Authorization header such as [Oracle VBS Git Repositories](https://docs.oracle.com/en/cloud/paas/visual-builder/visualbuilder-manage-development-process/access-git-repository-using-token-based-authentication.html):

```sh
flux bootstrap git \
  --url=https://<host>/<org>/<repository> \
  --password=<Access Token> \
  --with-bearer-token \
  --path=clusters/my-cluster
```

If your Git server uses a self-signed TLS certificate, you can specify the CA file with
`--ca-file=<path/to/ca.crt>`.

## Bootstrap multiple clusters

With `--path` you can configure the directory which will be used to reconcile the target cluster.
To control multiple clusters from the same Git repository, you have to set a unique path per
cluster e.g. `clusters/staging` and `clusters/production`:

```sh
./clusters/
├── staging # <- path=clusters/staging
│   └── flux-system # <- namespace dir generated by bootstrap
│       ├── gotk-components.yaml
│       ├── gotk-sync.yaml
│       └── kustomization.yaml
└── production # <- path=clusters/production
    └── flux-system
```

{{% alert color="info" title="Bootstrap options" %}}
There are many options available when bootstrapping Flux, such as installing a subset of Flux components,
setting the Kubernetes context, changing the Git author name and email, enabling Git submodules, and more.
To list all the available options run `flux bootstrap git --help`.
{{% /alert %}}
