Tutorial: Set up Flux for GitOps

This tutorial teaches you how to set up Flux for GitOps. You’ll set up a sample project, complete a bootstrap Flux installation, and authenticate your installation with a project access token.

You can find the fully configured tutorial project in this GitLab repository. It works in conjunction with this repository, which contains the example Kubernetes manifests.

To set up Flux with a project access token:

  1. Create the Flux repository
  2. Create the Kubernetes manifest repository
  3. Configure Flux to sync your manifests
  4. Verify your configuration


  • On GitLab SaaS, you must have the Premium or Ultimate tier to use a project access token. On self-managed instances, you can have any tier.
  • Not recommended. You can authenticate with a personal or group access token in all tiers.
  • You must have a Kubernetes cluster running.

Create the Flux repository

To start, create a Git repository, install Flux, and authenticate Flux with your repo:

  1. Make sure your kubectl is configured to access your cluster.
  2. Install the Flux CLI.
  3. In GitLab, create a new empty project called flux-config.
  4. In the flux-config project, create a project access token with the following settings:

    • From the Select a role dropdown list, select Maintainer.
    • Under Select scopes, select the API and write_repository checkboxes.

    Name the project token flux-project-access-token.

  5. From your shell, export a GITLAB_TOKEN environment variable with the value of your project access token. For example, export GITLAB_TOKEN=<flux-project-access-token>.
  6. Run the bootstrap command. The exact command depends on whether you are creating the Flux repository under a GitLab user, group, or subgroup. For more information, see the Flux bootstrap documentation.

    In this tutorial, you’re working with a public project in a subgroup. The bootstrap command looks like this:

    flux bootstrap gitlab \
      --owner=gitlab-org/configure/examples/flux \
      --repository=flux-config \
      --branch=main \

    This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository flux-config.

Great work! You now have a repository, a project access token, and a Flux bootstrap installation authenticated to your repo. Any updates to your repo are automatically synced to the cluster.

Create the Kubernetes manifest repository

Next, create a repository for your Kubernetes manifests:

  1. In GitLab, create a new repository called web-app-manifests.
  2. Add a file to web-app-manifests named nginx-deployment.yaml with the following contents:

    apiVersion: apps/v1
    kind: Deployment
      name: nginx-deployment
        app: nginx
      replicas: 3
          app: nginx
            app: nginx
          - name: nginx
            image: nginx:1.14.2
            - containerPort: 80
  3. In the new repository, create a deploy token with only the read_repository scope.
  4. Store your deploy token username and password somewhere safe.
  5. In Flux CLI, create a secret with your deploy token and point the secret to the new repository. For example:

    flux create secret git flux-deploy-authentication \
             --url=https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests \
             --namespace=default \
             --username=<token-user-name> \
  6. To check if your secret was generated successfully, run:

    kubectl -n default get secrets flux-deploy-authentication -o yaml

    Under data, you should see base64-encoded values associated with your token username and password.

Congratulations! You now have a manifest repository, a deploy token, and a secret generated directly on your cluster.

Configure Flux to sync your manifests

Next, tell flux-config to sync with the web-app-manifests repository.

To do so, create a GitRepository resource:

  1. Clone the flux-config repo to your machine.
  2. In your local clone of flux-config, add the GitRepository file clusters/my-cluster/web-app-manifests-source.yaml:

    apiVersion: source.toolkit.fluxcd.io/v1beta2
    kind: GitRepository
      name: web-app-manifests
      namespace: default
      interval: 1m0s
        branch: main
        name: flux-deploy-authentication
      url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests

    This file uses secretRef to refer back to the deploy token secret you created in the last step.

  3. In your local clone of flux-config, add the GitRepository file clusters/my-cluster/web-app-manifests-kustomization.yaml:

    apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
    kind: Kustomization
      name: nginx-source-kustomization
      namespace: default
      interval: 1m0s
      path: ./
      prune: true
        kind: GitRepository
        name: web-app-manifests
        namespace: default
      targetNamespace: default

    This file adds a Kustomization resource that tells Flux to sync the manifests from web-app-manifests with kustomize.

  4. Commit the new files and push.

Verify your configuration

You should see a newly created nginx-deployment pod in your cluster.

To check whether the nginx-deployment pod is running in the default namespace, run the following:

kubectl -n default get pods -n default

If you want to see the deployment sync again, try updating the number of replicas in the nginx-deployment.yaml file and push to your main branch. If all is working well, it should sync to the cluster.

Excellent work! You’ve successfully set up a complete Flux project.