GitLab CI/CD Pipeline

Build images with GitLab CI and deploy them by committing the new tag to a GitOps repository on GitHub or Bitbucket Cloud

This guide shows you how to build a CI/CD pipeline with GitLab CI that automatically deploys your applications to Kubernetes when you push code. Your pipeline builds container images and updates the GitOps repository. Ankra handles the rest.

The GitOps repository cannot be on GitLab. Ankra syncs a cluster’s GitOps repository from GitHub or Bitbucket Cloud only. Your application code and GitLab CI stay on GitLab; the pipeline in this guide commits the new image tag to a GitOps repository on GitHub. For the other routes from a repository to a running application, see Ship Your App.

---

Architecture Overview

The flow works like this:

1. You push code to your GitLab application repository
2. GitLab CI builds and pushes a container image to your registry
3. GitLab CI updates the GitOps repo with the new image tag
4. Ankra detects the change and triggers a deployment
5. Ankra Agent deploys the updated manifest to your cluster

---

What You’ll Build

A complete CI/CD pipeline with:

Component	Purpose
Application Repo	Your app code with Dockerfile and .gitlab-ci.yml
GitOps Repo	Kubernetes manifests managed by Ankra, on GitHub or Bitbucket Cloud
Container Registry	Stores your built images (GitLab Container Registry, GCR, ECR, etc.)
GitLab CI	Builds images and updates the GitOps repo

---

Prerequisites

• A cluster imported into Ankra with the agent connected
• A GitOps repository on GitHub (this guide) or Bitbucket Cloud
• A container registry (GitLab Container Registry, Google Artifact Registry, AWS ECR, Docker Hub, etc.)
• An application repository on GitLab with a Dockerfile

---

Step 1: Connect a GitOps Repository to the Cluster

Connect the repository that will hold the cluster’s configuration. It must be on GitHub or Bitbucket Cloud.

1. Open the cluster's GitOps settings

   Go to your cluster → Settings → GitOps.

2. Connect the repository

   Pick a GitHub or Bitbucket Cloud credential, then the repository and branch, and click Connect Repository. The GitHub and Bitbucket Cloud guides cover the credential and each screen.

   We recommend a dedicated repository (for example my-org/infrastructure-gitops) to keep cluster configuration separate from application code.

Once connected, Ankra writes the cluster’s configuration to a clusters/<cluster-name>-<short-id>/ folder in the repository and keeps it in sync.

---

Step 2: Create a Stack for Your Application

In Ankra, manifests are organized into Stacks. A Stack is a collection of related Kubernetes resources that are deployed together.

1. Open the Stacks Page

   Navigate to your cluster → Stacks.

2. Create a New Stack

   Click Create to open the Stack Builder.

3. Name Your Stack

   Give your stack a descriptive name, like backend-services or production-apps.

4. Add a Manifest Using AI

   Press ⌘+J (or Ctrl+J) to open the AI Assistant and describe your deployment:

   Create a deployment manifest for my backend service:
   - Image: registry.gitlab.com/my-group/my-app/backend:sha-1a2b3c4d
   - Namespace: production
   - 2 replicas
   - Port 8080
   - Health check on /health
   - 256Mi memory, 100m CPU requests
   

   The AI will provide a manifest you can add to your stack.

5. Create the Stack

   Review your configuration in the Builder tab, then click Create Stack.

   Ankra will commit the manifests to your GitOps repository and deploy them to your cluster.

You can view your stack’s manifests in the GitOps repository under clusters/<cluster-name>-<short-id>/stacks/<stack-name>/manifests/.

---

Step 3: Set Up CI Deploy Key

Your GitLab CI pipeline needs write access to the GitOps repository to update image tags when new builds complete.

1. Generate an SSH Key

   On your local machine, generate a deploy key:

   ssh-keygen -t ed25519 -C "ci-deploy-key" -f deploy_key -N ""
   

   This creates deploy_key (private) and deploy_key.pub (public).

2. Add Public Key to GitOps Repo

   Go to your GitOps repository on GitHub → Settings → Deploy keys → Add deploy key.

   Add the contents of deploy_key.pub and check Allow write access.

   On Bitbucket Cloud, repository access keys are read-only, so they cannot push. Use a repository access token with write permission over HTTPS instead.

3. Add Private Key to App Repo

   Go to your application repository → Settings → CI/CD → Variables.

   Create a new variable:

   • Key: GITOPS_DEPLOY_KEY
   • Value: Contents of deploy_key
   • Type: File
   • Flags: Check Mask variable and Protect variable

---

Step 4: Create the GitLab CI Pipeline

Add a .gitlab-ci.yml file to your application repository that builds your container and updates the GitOps repo.

1. Create the Pipeline File

   In your application repository, create .gitlab-ci.yml at the root.

2. Use the AI to Generate the Pipeline

   Open the AI Assistant (⌘+J) and describe your pipeline:

   Generate a GitLab CI pipeline that:
   - Triggers on push to main branch
   - Builds a Docker image from my Dockerfile
   - Pushes to GitLab Container Registry
   - Tags with the git SHA, never latest
   - Updates my GitOps repo at github.com/my-org/infrastructure-gitops
   - Updates the image tag in clusters/my-cluster-<short-id>/stacks/backend-services/manifests/backend-deployment.yaml
   

   The AI will generate a complete pipeline tailored to your setup.

3. Add Registry Variables

   If using an external registry (not GitLab Container Registry), add these variables under Settings → CI/CD → Variables:

   Variable	Description
   REGISTRY_USERNAME	Registry username (or _json_key for GCP)
   REGISTRY_PASSWORD	Registry password or service account key
   GITOPS_DEPLOY_KEY	The SSH private key from Step 3

   GitLab Container Registry is available by default in GitLab CI via $CI_REGISTRY, $CI_REGISTRY_USER, and $CI_REGISTRY_PASSWORD - no extra variables needed.

Example Pipeline: GitLab Container Registry

Here’s a pipeline using GitLab’s built-in container registry. It tags every image with the commit SHA, never latest, so each deploy names exactly one build. Use the AI to customise it for your setup:

stages:
  - build
  - deploy

variables:
  IMAGE_NAME: $CI_REGISTRY_IMAGE/backend
  GITOPS_REPO: [e-mail]:my-org/infrastructure-gitops.git
  MANIFEST_PATH: clusters/my-cluster-<short-id>/stacks/backend-services/manifests/backend-deployment.yaml

build:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - src/**/*
        - Dockerfile
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $IMAGE_NAME:$CI_COMMIT_SHA .
    - docker push $IMAGE_NAME:$CI_COMMIT_SHA

update-gitops:
  stage: deploy
  image: alpine:3.20
  needs: [build]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - src/**/*
        - Dockerfile
  before_script:
    - apk add --no-cache git openssh-client sed
    - eval $(ssh-agent -s)
    - chmod 600 $GITOPS_DEPLOY_KEY
    - ssh-add $GITOPS_DEPLOY_KEY
    - mkdir -p ~/.ssh
    - ssh-keyscan github.com >> ~/.ssh/known_hosts
  script:
    - git clone $GITOPS_REPO gitops-repo
    - cd gitops-repo
    - "sed -i \"s|image: .*backend:.*|image: ${IMAGE_NAME}:${CI_COMMIT_SHA}|\" $MANIFEST_PATH"
    - git config user.name "GitLab CI"
    - git config user.email "[e-mail]"
    - git add $MANIFEST_PATH
    - git commit -m "Deploy backend: $CI_COMMIT_SHA"
    - git push origin main

Example Pipeline: Google Artifact Registry

Here’s a pipeline pushing to Google Artifact Registry:

stages:
  - build
  - deploy

variables:
  IMAGE_NAME: europe-west1-docker.pkg.dev/my-project/docker-images/backend
  GITOPS_REPO: [e-mail]:my-org/infrastructure-gitops.git
  MANIFEST_PATH: clusters/my-cluster-<short-id>/stacks/backend-services/manifests/backend-deployment.yaml

build:
  stage: build
  image: docker:27
  services:
    - docker:27-dind
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - src/**/*
        - Dockerfile
  script:
    - echo "$GCP_SERVICE_ACCOUNT_KEY" | docker login -u _json_key --password-stdin https://europe-west1-docker.pkg.dev
    - docker build -t $IMAGE_NAME:$CI_COMMIT_SHA .
    - docker push $IMAGE_NAME:$CI_COMMIT_SHA

update-gitops:
  stage: deploy
  image: alpine:3.20
  needs: [build]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - src/**/*
        - Dockerfile
  before_script:
    - apk add --no-cache git openssh-client sed
    - eval $(ssh-agent -s)
    - chmod 600 $GITOPS_DEPLOY_KEY
    - ssh-add $GITOPS_DEPLOY_KEY
    - mkdir -p ~/.ssh
    - ssh-keyscan github.com >> ~/.ssh/known_hosts
  script:
    - git clone $GITOPS_REPO gitops-repo
    - cd gitops-repo
    - "sed -i \"s|image: .*backend:.*|image: ${IMAGE_NAME}:${CI_COMMIT_SHA}|\" $MANIFEST_PATH"
    - git config user.name "GitLab CI"
    - git config user.email "[e-mail]"
    - git add $MANIFEST_PATH
    - git commit -m "Deploy backend: $CI_COMMIT_SHA"
    - git push origin main

---

Step 5: Configure Registry Access in Your Cluster

If your container registry is private, your cluster needs credentials to pull images.

1. Open the AI Assistant

   Press ⌘+J to open the AI Assistant.

2. Ask for an Image Pull Secret

   Create an image pull secret for my private registry:
   - Registry: registry.gitlab.com
   - Namespace: production
   - Name: gitlab-pull-secret
   
3. Add the Secret Value

   The AI will provide a Secret manifest template. You’ll need to provide your registry credentials:

   • For GitLab: Use a Deploy Token with read_registry scope
   • For GCP: Use a service account JSON key with Artifact Registry Reader role
   • For AWS ECR: Use an IAM access key
4. Link to Your Deployment

   Ask the AI to update your deployment to use the pull secret:

   Update my backend deployment to use the gitlab-pull-secret for pulling images
   

Use SOPS encryption to safely store registry credentials in your GitOps repository.

---

Step 6: Test the Pipeline

1. Push a Code Change

   Make a change to your application code and push to main:

   git add .
   git commit -m "Add new feature"
   git push origin main
   
2. Monitor CI Progress

   Go to CI/CD → Pipelines in your GitLab project to watch the pipeline run.

3. Verify GitOps Update

   After CI completes, check your GitOps repository. You should see a new commit updating the image tag.

4. Watch the Deployment

   In Ankra, go to your cluster → Operations to see the deployment in progress. The new image will roll out automatically.

---

Step 7: Monitor GitOps Sync Status

Ankra provides visibility into your GitOps sync status.

1. View GitOps Status

   Navigate to your cluster → GitOps to see:

   • Current sync status
   • Recent sync history
   • Any sync errors
2. Trigger Manual Sync

   If needed, click Sync to manually trigger a sync from your repository.

3. View in Operations

   Check the Operations page for detailed deployment history and job status.

---

Adding More Services

To add CI/CD for additional services, use the AI Assistant to scaffold everything:

1. Add to Existing Stack or Create New

   Either edit your existing stack or create a new one for the service.

2. Generate the Deployment Manifest

   Open the AI Assistant (⌘+J) and describe your service:

   Add a deployment for my frontend service:
   - Image: registry.gitlab.com/my-group/my-app/frontend
   - Namespace: production
   - 3 replicas
   - Port 3000
   - Expose via a Service on port 80
   
3. Generate the CI Pipeline

   In your frontend app repo, create a .gitlab-ci.yml or ask the AI:

   Generate a GitLab CI pipeline to build and deploy my frontend:
   - Build from ./frontend/Dockerfile
   - Push to GitLab Container Registry
   - Update clusters/my-cluster/manifests/frontend-deployment.yaml in my GitOps repo
   
4. Add the Variables

   Copy the same CI/CD variables (GITOPS_DEPLOY_KEY, registry credentials) to the new project.

---

Troubleshooting

Having issues? Open the AI Assistant (⌘+J) and describe your problem:

CI Can't Push to GitOps Repo

Ask the AI:

My GitLab CI pipeline is failing to push to the GitOps repo with a permission denied error.
Help me troubleshoot the deploy key setup.

Common causes:

• Deploy key doesn’t have write permissions on the GitOps repo
• GITOPS_DEPLOY_KEY variable is not set as File type
• ssh-keyscan is missing for github.com

Image Not Updating

Ask the AI:

I pushed a new image tag to my GitOps repo but the pods aren't updating.
What could be wrong?

Pods Can't Pull Image

Ask the AI:

My pods are stuck in ImagePullBackOff. Help me fix the registry authentication.

For GitLab Container Registry, ensure your image pull secret uses a Deploy Token with read_registry scope.

Pipeline Fails on Docker Build

Ensure your GitLab Runner supports Docker-in-Docker:

• Use docker:27 as the job image
• Add docker:27-dind as a service
• If using Kubernetes executors, ensure privileged mode is enabled or use Kaniko instead

GitOps Sync Not Triggering

Check the GitOps page in your cluster to see sync status. If sync isn’t triggering:

• Verify the GitOps repository is still connected under the cluster’s Settings → GitOps
• Check that your commit was pushed to the correct branch
• Look for webhook configuration issues in the GitOps status

The AI has access to your pod logs, events, and deployment status. It can pinpoint exactly what’s going wrong and suggest fixes.

---

Next Steps

Ship Your App

Compare the routes from a repository to a running application, including GitHub Actions.

GitOps Reference

Learn more about GitOps file formats and include paths.

SOPS Encryption

Encrypt secrets in your GitOps repository.

Operations

Monitor deployment progress and history.