Tutorial: Deploy a Git repository using Flux

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

In this tutorial, you’ll create a GitLab project that builds and deploys an application to a Kubernetes cluster using Flux. You’ll set up a sample manifest project, configure it to push manifests to a deployment branch, and configure Flux to sync the deployment branch. With this setup, you can run additional steps in GitLab pipelines before Flux picks up the changes from the repository.

This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a project deploy token.

To set up a repository for GitOps deployments:

  1. Create the Kubernetes manifest repository
  2. Create a deployment branch
  3. Configure GitLab CI/CD to push to your branch
  4. Configure Flux to sync your manifests
  5. Verify your configuration


  • You have a Flux repository connected to a Kubernetes cluster. If you’re starting from scratch, see Set up Flux for GitOps.

Create the Kubernetes manifest repository

First, create a repository for your Kubernetes manifests:

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

    apiVersion: apps/v1
    kind: Deployment
      name: nginx
      replicas: 1
          - name: nginx
            image: nginx:1.14.2
            - containerPort: 80
  3. In web-app-manifests, add a file named src/kustomization.yaml with the following contents:

    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
      - nginx-deployment.yaml
      app: flux-branches-tutorial

Create a deployment branch

Next, create a branch to reflect the current state of your cluster.

In this workflow, the default branch is the single source of truth for your application. To be reflected in a Kubernetes cluster, a code or configuration change must exist in the default branch. In a later step, you’ll configure CI/CD to merge changes from the default branch into the deployment branch.

To create a deployment branch:

  1. In web-app-manifests, create a branch named _gitlab/deploy/example from the default branch. The branch name in this example is chosen to differentiate the deployment branch from feature branches, but this is not required. You can name the deployment branch whatever you like.
  2. Create a project, group or personal access token with the write_repository scope.
  3. Create a CI/CD variable with a token value named DEPLOYMENT_TOKEN. Remember to mask the value so that it won’t show in job logs.
  4. Add a rule to protect your deployment branch with the following values:

    • Allowed to merge: No one.
    • Allowed to push and merge: Select the token you created in the previous step, or your user if you created a personal access token.
    • Allowed to force push: Turn off the toggle.
    • Require approval from code owners: Turn off the toggle.

This configuration ensures that only the corresponding token can push to the branch.

You’ve successfully created a repository with a protected deployment branch!

Configure GitLab CI/CD to push to your branch

Next, you’ll configure CI/CD to merge changes from the default branch to your deployment branch.

In the root of web-app-manifests, create and push a .gitlab-ci.yml file with the following contents:

     stage: deploy
     environment: production
       DEPLOYMENT_BRANCH: _gitlab/deploy/example
       - |
         git config user.name "Deploy Example Bot"
         git config user.email "test@example.com"
         git fetch origin $DEPLOYMENT_BRANCH
         git checkout $DEPLOYMENT_BRANCH
         git merge $CI_COMMIT_SHA --ff-only
     resource_group: $CI_ENVIRONMENT_SLUG

This creates a CI/CD pipeline with a single deploy job that:

  1. Checks out your deployment branch.
  2. Merges new changes from the default branch into the deployment branch.
  3. Pushes the changes to your repository with the configured token.

Configure Flux to sync your manifests

Next, configure your Flux repository to sync the deployment branch in by the web-app-manifests repository.

To configure, create a GitRepository resource:

  1. In your local clone of your Flux repository, add a file named clusters/my-cluster/web-app-manifests-source.yaml with the following contents:

    apiVersion: source.toolkit.fluxcd.io/v1
    kind: GitRepository
      name: web-app-manifests
      namespace: flux-system
      interval: 5m0s
      url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-branches
        branch: _gitlab/deploy/example

    You will need to substitute the url with the URL of your web-app-manifests project.

  2. In your local clone of your Flux repository, add a file named clusters/my-cluster/web-app-manifests-kustomization.yaml with the following contents:

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

    This file adds a Kustomization resource that tells Flux to sync the manifests in the artifact fetched from the registry.

  3. Commit the new files and push.

Verify your configuration

After the pipeline completes, you should see a newly created nginx pod in your cluster.

If you want to see the deployment sync again, try updating the number of replicas in the src/nginx-deployment.yaml file and push to the default branch. If all is working well, the change will sync to the cluster when the pipeline has finished.

Congratulations! You successfully configured a project to deploy an application and synchronize your changes!