GitLab CI/CD Pipeline

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.

Architecture Overview

The flow works like this:

You push code to your GitLab application repository
GitLab CI builds and pushes a container image to your registry
GitLab CI updates the GitOps repo with the new image tag
Ankra detects the change and triggers a deployment
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
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 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 GitLab Repository

First, connect a GitLab repository to your cluster. This enables GitOps and installs the necessary components on your cluster.

Navigate to Integration Settings

Go to your cluster → Settings → Integration tab.

Add a GitLab Credential

If you haven’t connected GitLab yet, add a new credential:

Go to Credentials and create a new Git credential
Select GitLab as the provider
Provide your GitLab URL and a Personal Access Token with api and read_repository scopes

Select a Repository

Choose the repository that will store your GitOps configuration.

We recommend creating a dedicated repository (e.g., infrastructure-gitops) to keep your cluster configurations separate from application code.

Confirm Installation

When you connect for the first time, Ankra will install:

ArgoCD - GitOps continuous delivery
Ankra Stack Builder - Declarative infrastructure management
Ankra Resource Engine - Intelligent resource orchestration
GitOps Monitoring - Continuous deployment from your repository

Click Install ArgoCD & Connect to proceed.

Once connected, Ankra will create the repository structure and begin syncing your cluster configuration.

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.

Open the Stacks Page

Navigate to your cluster → Stacks.

Create a New Stack

Click Create to open the Stack Builder.

Name Your Stack

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

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:latest
- 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.

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}/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.

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).

Add Public Key to GitOps Repo

Go to your GitOps repository on GitLab → Settings → Repository → Deploy keys.Add the contents of deploy_key.pub and check Grant write permissions to this key.

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.

Create the Pipeline File

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

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
- Updates my GitOps repo at gitlab.com/my-group/infrastructure-gitops
- Updates the image tag in clusters/my-cluster/manifests/backend-deployment.yaml

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

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. Use the AI to customize it for your setup:

stages:
  - build
  - deploy

variables:
  IMAGE_NAME: $CI_REGISTRY_IMAGE/backend
  GITOPS_REPO: [email protected]:my-group/infrastructure-gitops.git
  MANIFEST_PATH: clusters/my-cluster/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 -t $IMAGE_NAME:latest .
    - docker push $IMAGE_NAME:$CI_COMMIT_SHA
    - docker push $IMAGE_NAME:latest

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 gitlab.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 "[email protected]"
    - 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: [email protected]:my-group/infrastructure-gitops.git
  MANIFEST_PATH: clusters/my-cluster/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 gitlab.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 "[email protected]"
    - 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.

Open the AI Assistant

Press ⌘+J to open the AI Assistant.

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

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

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

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

Monitor CI Progress

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

Verify GitOps Update

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

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.

View GitOps Status

Navigate to your cluster → GitOps to see:

Current sync status
Recent sync history
Any sync errors

Trigger Manual Sync

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

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:

Add to Existing Stack or Create New

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

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

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

Add the Variables

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

Common AI Prompts

Use these prompts with the AI Assistant (⌘+J) to set up your CI/CD:

Create a Deployment

Create a deployment manifest for my backend service:
- Image: registry.gitlab.com/my-group/backend:latest
- Namespace: production
- 2 replicas with rolling update strategy
- Port 8080
- Health checks on /health and /ready
- Resource requests: 256Mi memory, 100m CPU
- Resource limits: 512Mi memory, 500m CPU
- Environment variables from a ConfigMap called backend-config

Create a Complete Service Stack

Set up a complete service stack for my API:
- Deployment with 3 replicas
- Service exposing port 80
- Ingress with TLS using cert-manager
- HorizontalPodAutoscaler scaling 2-10 replicas at 70% CPU
- PodDisruptionBudget allowing 1 unavailable

Add Image Pull Secret

Create a docker registry secret for pulling images from:
- Registry: registry.gitlab.com
- Namespace: production

Then update my backend deployment to use this secret.

Generate GitLab CI Pipeline

Generate a GitLab CI pipeline that:
- Builds my Docker image on push to main
- Pushes to GitLab Container Registry
- Updates clusters/prod/manifests/app-deployment.yaml in my GitOps repo
- Only builds when files in src/ or Dockerfile change

Troubleshoot Deployment

My backend deployment isn't updating after CI pushed a new image.
Help me troubleshoot why the pods aren't rolling out.

The AI Assistant has full context of your cluster. It can see your existing resources, logs, and events. Describe what you want to achieve and it will generate the right configuration.

Best Practices

Use Immutable Image Tags

Always use unique, immutable tags like $CI_COMMIT_SHA or $CI_PIPELINE_ID. Avoid relying solely on latest.Ask the AI: “Ensure my deployment uses immutable image tags and imagePullPolicy IfNotPresent”

Use GitLab Deploy Tokens for Pull Access

Instead of using Personal Access Tokens, create Deploy Tokens with read_registry scope for image pull secrets. They’re scoped to a project and easy to rotate.

Add Health Checks

Let the AI configure proper health checks for your deployments.Ask the AI: “Add appropriate liveness and readiness probes to my backend deployment for a Node.js app”

Set Resource Limits

Prevent runaway resource usage with proper limits.Ask the AI: “Review my deployment and suggest appropriate resource requests and limits based on a typical web API”

Use SOPS for Secrets

Encrypt sensitive values in your GitOps repository.Ask the AI: “Help me encrypt my database password using SOPS”

Protect CI/CD Variables

Mark sensitive variables as Protected and Masked in GitLab CI/CD settings. Use File type for SSH keys to avoid shell escaping issues.

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 the GitLab host

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 GitLab repository is still connected in Settings → Integration
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

GitHub CI/CD Pipeline

See the equivalent guide for 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.

Get Started

Concepts

Provision & Import

Operate & Secure

Deliver

Platform

AI

Kubernetes Resources

Reference

Integrations

Architecture Overview

What You’ll Build

Prerequisites

Step 1: Connect a GitLab Repository

Step 2: Create a Stack for Your Application

Step 3: Set Up CI Deploy Key

Step 4: Create the GitLab CI Pipeline

Step 5: Configure Registry Access in Your Cluster

Step 6: Test the Pipeline

Step 7: Monitor GitOps Sync Status

Adding More Services

Common AI Prompts

Best Practices

Troubleshooting

Next Steps

GitHub CI/CD Pipeline

GitOps Reference

SOPS Encryption

Operations

​Architecture Overview

​What You’ll Build

​Prerequisites

​Step 1: Connect a GitLab Repository

​Step 2: Create a Stack for Your Application

​Step 3: Set Up CI Deploy Key

​Step 4: Create the GitLab CI Pipeline

​Step 5: Configure Registry Access in Your Cluster

​Step 6: Test the Pipeline

​Step 7: Monitor GitOps Sync Status

​Adding More Services

​Common AI Prompts

​Best Practices

​Troubleshooting

​Next Steps

GitHub CI/CD Pipeline

GitOps Reference

SOPS Encryption

Operations

Architecture Overview

What You’ll Build

Prerequisites

Step 1: Connect a GitLab Repository

Step 2: Create a Stack for Your Application

Step 3: Set Up CI Deploy Key

Step 4: Create the GitLab CI Pipeline

Step 5: Configure Registry Access in Your Cluster

Step 6: Test the Pipeline

Step 7: Monitor GitOps Sync Status

Adding More Services

Common AI Prompts

Best Practices

Troubleshooting

Next Steps