Add Ankra GitOps to your app

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

Architecture Overview

The flow works like this:

You push code to your application repository
CI builds and pushes a container image to your registry
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 CI workflow
GitOps Repo	Kubernetes manifests managed by Ankra
Container Registry	Stores your built images (GCR, ECR, Docker Hub, etc.)
GitHub Actions	Builds images and updates the GitOps repo

Prerequisites

A cluster imported into Ankra with the agent connected
A container registry (Google Artifact Registry, AWS ECR, Docker Hub, etc.)
An application repository with a Dockerfile

Step 1: Connect a GitHub Repository

First, connect a GitHub 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 GitHub Credential

If you haven’t connected GitHub yet, you’ll see a prompt to connect a repository.Select an existing GitHub credential from the dropdown, or click to add a new one. This authorizes Ankra to access your repositories.

Select a Repository

Choose the repository that will store your GitOps configuration. This can be an existing repo or a new one.

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: europe-west1-docker.pkg.dev/my-project/docker-images/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 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 GitHub → Settings → Deploy keys → Add deploy key.Paste the contents of deploy_key.pub and check Allow write access.

Add Private Key to App Repo

Go to your application repository → Settings → Secrets and variables → Actions.Create a new secret called GITOPS_DEPLOY_KEY with the contents of deploy_key.

Step 4: Create the CI Workflow

Add a GitHub Actions workflow to your application repository that builds your container and updates the GitOps repo.

Create the Workflow File

In your application repository, create .github/workflows/deploy.yml.

Use the AI to Generate the Workflow

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

Generate a GitHub Actions workflow that:
- Triggers on push to main branch
- Builds a Docker image from my Dockerfile
- Pushes to Google Artifact Registry at europe-west1-docker.pkg.dev/my-project/docker-images/backend
- Tags with the git SHA
- Updates my GitOps repo at github.com/my-org/infrastructure-gitops
- Updates the image tag in clusters/my-cluster/manifests/backend-deployment.yaml

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

Add Registry Secrets

Add these secrets to your application repository under Settings → Secrets and variables → Actions:

Secret	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

Example Workflow Reference

Here’s what a typical workflow looks like. Use the AI to customize it for your specific setup:

name: Build and Deploy

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'Dockerfile'
  workflow_dispatch:

env:
  IMAGE_NAME: europe-west1-docker.pkg.dev/my-project/docker-images/backend
  GITOPS_REPO: [email protected]:my-org/infrastructure-gitops.git
  MANIFEST_PATH: clusters/my-cluster/manifests/backend-deployment.yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          registry: europe-west1-docker.pkg.dev
          username: _json_key
          password: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}

      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ env.IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  update-gitops:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.GITOPS_DEPLOY_KEY }}

      - name: Update GitOps repo
        run: |
          git clone ${{ env.GITOPS_REPO }}
          cd infrastructure-gitops

          git config user.name "GitHub Actions"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          sed -i "s|${{ env.IMAGE_NAME }}:[a-zA-Z0-9_-]*|${{ env.IMAGE_NAME }}:${{ github.sha }}|" "${{ env.MANIFEST_PATH }}"

          git add "${{ env.MANIFEST_PATH }}"
          git commit -m "Deploy backend: ${{ github.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: europe-west1-docker.pkg.dev
- Namespace: production
- Name: gcr-pull-secret

Add the Secret Value

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

For GCP: Use a service account JSON key with Artifact Registry Reader role
For AWS ECR: Use an IAM access key
For Docker Hub: Use your username and access token

Link to Your Deployment

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

Update my backend deployment to use the gcr-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 Actions in your application repository to watch the workflow 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: europe-west1-docker.pkg.dev/my-project/docker-images/frontend
- Namespace: production
- 3 replicas
- Port 3000
- Expose via a Service on port 80

Generate the CI Workflow

In your frontend app repo, ask the AI to generate the workflow:

Generate a GitHub Actions workflow to build and deploy my frontend:
- Build from ./frontend/Dockerfile
- Push to europe-west1-docker.pkg.dev/my-project/docker-images/frontend
- Update clusters/my-cluster/manifests/frontend-deployment.yaml in my GitOps repo

Add the Secrets

Copy the same secrets (GITOPS_DEPLOY_KEY, registry credentials) to the new repository.

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: my-registry.io/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: europe-west1-docker.pkg.dev
- Namespace: production

Then update my backend deployment to use this secret.

Generate CI Workflow

Generate a GitHub Actions workflow that:
- Builds my Docker image on push to main
- Pushes to AWS ECR at 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app
- Updates clusters/prod/manifests/app-deployment.yaml in my GitOps repo
- Only builds when files in src/ or Dockerfile change

Add Canary Deployment

Modify my deployment to support canary releases:
- Create a canary deployment with 1 replica
- Use labels to route 10% of traffic to canary
- Add a Service that selects both stable and canary pods

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 git SHA or build number. The AI will help you set this up correctly.Ask the AI: “Ensure my deployment uses immutable image tags and imagePullPolicy IfNotPresent”

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”

Troubleshooting

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

CI Can't Push to GitOps Repo

Ask the AI:

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

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.

Deployment Rollout Stuck

Ask the AI:

My deployment rollout is stuck. Show me what's blocking it and how to fix it.

GitOps Sync Not Triggering

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

Verify the GitHub 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

GitOps Reference

Learn more about GitOps file formats and include paths.

SOPS Encryption

Encrypt secrets in your GitOps repository.

Webhooks

Trigger external systems when deployments complete.

Operations

Monitor deployment progress and history.

Get Started

Guides

Clusters

Stacks & Add-ons

GitOps

Kubernetes Resources

Platform Features

Team & Settings

Integrations

Add Ankra GitOps to your app

Architecture Overview

What You’ll Build

Prerequisites

Step 1: Connect a GitHub Repository

Step 2: Create a Stack for Your Application

Step 3: Set Up CI Deploy Key

Step 4: Create the CI Workflow

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

GitOps Reference

SOPS Encryption

Webhooks

Operations

Get Started

Guides

Clusters

Stacks & Add-ons

GitOps

Kubernetes Resources

Platform Features

Team & Settings

Integrations

​Architecture Overview

​What You’ll Build

​Prerequisites

​Step 1: Connect a GitHub Repository

​Step 2: Create a Stack for Your Application

​Step 3: Set Up CI Deploy Key

​Step 4: Create the CI Workflow

​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

GitOps Reference

SOPS Encryption

Webhooks

Operations

Architecture Overview

What You’ll Build

Prerequisites

Step 1: Connect a GitHub Repository

Step 2: Create a Stack for Your Application

Step 3: Set Up CI Deploy Key

Step 4: Create the CI Workflow

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