Flux bootstrap for Gitea

The flux bootstrap gitea command deploys the Flux controllers on a Kubernetes cluster and configures the controllers to sync the cluster state from a Gitea repository. Besides installing the controllers, the bootstrap command pushes the Flux manifests to the Gitea repository and configures Flux to update itself from Gitea.

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.

Gitea PAT

For accessing the Gitea API, the boostrap command requires a Gitea personal access token (PAT) with the following permissions:

• read:misc
• write:repository

If you want Flux to to create a new personal repository with Flux the following permissions are necessary:

• read:misc
• write:repository
• write:user

If you want Flux to to create a new organization repository with Flux the following permissions are necessary:

• read:misc
• write:organization
• write:repository

The Gitea PAT can be exported as an environment variable:

export GITEA_TOKEN=<gt-token>

If the GITEA_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 "<gt-token>" | flux bootstrap gitea.

Gitea Personal Account

Run the bootstrap for a repository on your personal Gitea account:

flux bootstrap gitea \
  --token-auth \
  --owner=my-gitea-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 --private=false.

When using --token-auth, the CLI and the Flux controllers running on the cluster will use the Gitea PAT to access the Git repository over HTTPS.

Gitea Organization

If you want to bootstrap Flux for a repository owned by a Gitea organization, it is recommended to create a dedicated user for Flux under your organization.

Run the bootstrap for a repository owned by a Gitea organization:

flux bootstrap gitea \
  `--token-auth` \
  --owner=my-gitea-organization \
  --repository=my-repository \
  --branch=main \
  --path=clusters/my-cluster

Gitea 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 Gitea 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 Gitea deploy key. The deploy key is linked to the personal access token used to authenticate.

By default, the Gitea 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.

Bootstrap without a Gitea PAT

For existing Gitea repositories, you can bootstrap Flux over SSH without using a Gitea PAT.

To use a SSH key instead of a Gitea PAT, the command changes to flux bootstrap git:

flux bootstrap git \
  --url=ssh://git@gitea.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 Gitea in advance.

For more information on how to use the flux bootstrap git command, please see the generic Git server documentation.