flux2/docs/guides/onboarding-private-repo.md

Onboarding a Private Git Repository

This guide walks you through the common use-case of onboarding a private GitRepository source.

The below examples and instructions assume you are using GitHub, but the same can apply for other providers and their support for access-token password auth.

Creating Per-Repo Deploy Keys

For detailed instructions on setting up per-repo deploy keys using SOPS/SSH- or token-based Git authentication, see the documentation in our flux2-multi-tenancy example.

Sharing Token Auth Across Repos

If you are managing a multi-tenant cluster with Flux, you can cut a Personal Access Token with repo access from a GitHub service account and use that token for authenticating multiple private GitRepository sources.

The benefits of sharing a token across multiple tenants instead of using per-repo deploy keys include:

• Control access for all of Flux using GitHub's ACLs like Teams (composes well if you're using Terraform to manage GitHub)
• You only have to manage/create one secret per cluster/namespace instead of per-repo.

The tradeoff is that revocation of access with a shared token is less granular than on a per-repo basis; you will have to manage access on the org/team/ user-level.

HTTP/S Basic Auth Token Access

1. Log into a GitHub service account that has admin access to the repo you are onboarding, and visit settings/tokens to generate a Personal Access Token with repo scope.
2. Bootstrap your cluster with the token. Note that we add the --token-auth flag, which lets Flux know that it should use your GITHUB_TOKEN permanently for auth in the cluster. If you already bootstrapped your cluster when getting started but did not add this flag, it is fine to re-run the bootstrap command.

export GITHUB_TOKEN=$GITHUB_TOKEN
flux bootstrap github \
  --owner=$GITHUB_USER \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/my-cluster \
  --token-auth

3. You can verify that Flux has saved your GITHUB_TOKEN for ongoing authentication by checking the flux-system secret in the flux-system namespace:

kubectl get secret flux-system -n flux-system -o yaml
# You should see the `data.username` and `data.password` fields

4. When onboarding a new GitRepository that is private, make sure to use the HTTP/S protocol in spec.url and reference the flux-system secret with your creds in spec.secretRef.

CLI Example

You can do this on the command-line like so:

flux create source git podinfo \
    --url=https://github.com/my-org/my-private-repo \
    --branch=master \
    --secret-ref=flux-system

YAML Manifest Example

If you are onboarding your source by checking in a YAML to your platform admin repo, it should look like this:

apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
    name: my-private-repo
    namespace: flux-system
spec:
    interval: 1m
    url: https://github.com/my-org/my-private-repo
    # since we are using a private GitHub repo, the below 
    # section is needed to tell Flux to use the GitHub token in the 
    # flux-system Secret for HTTP/S basic auth when syncing
    secretRef:
        name: flux-system
    ref:
        branch: master

Note on namespaces

Note that if you wish to manage your tenant GitRepository sources as part of a namespace that is not flux-system (e.g. the apps namespace, as in the multi-tenancy example), the private source will not be able to read from the flux-system Secret.

You will have to manually create a Kubernetes Secret with the data.username and data.password fields in the namespace that you are creating your GitRepository sources in. To keep Secrets private, consider using kubeseal.

# for GitRepository private sources stored in the `apps` namespace
kubectl create secret generic repo-auth -n apps \
	--from-literal=username=$GITHUB_USER \
	--from-literal=password=$GITHUB_TOKEN

To get your sources to use the Secret, just reference it by name in the GitRepository.spec.secretRef field:

apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
    name: my-private-repo
    namespace: apps
spec:
    interval: 1m
    url: https://github.com/my-org/my-private-repo
    secretRef:
        name: repo-auth
    ref:
        branch: master