Skip to main content

From Commit to Production: Hands-On GitOps Promotion with GitHub Actions, Argo CD, Helm, and Kargo

Nitheesh PoojaryJune 6, 2025About 16 minDevOpsKubernetesGithubGithub ActionsArticle(s)blogfreecodecamp.orgdevopsk8skubernetesgithubgithub-actions

From Commit to Production: Hands-On GitOps Promotion with GitHub Actions, Argo CD, Helm, and Kargo κ΄€λ ¨

Git > Article(s)
Article(s)
From Commit to Production: Hands-On GitOps Promotion with GitHub Actions, Argo CD, Helm, and Kargo
Have you ever wanted to go beyond β€˜hello world’ and build a real, production-style CI/CD pipeline – starting from scratch? Let’s pause for a moment: what are you trying to learn from your DevOps journey? Are you focusing on GitOps-style deployments, ...

Have you ever wanted to go beyond β€˜hello world’ and build a real, production-style CI/CD pipeline – starting from scratch?

Let’s pause for a moment: what are you trying to learn from your DevOps journey? Are you focusing on GitOps-style deployments, or promotions? This guide will help you tackle all of it – one step at a time.

As a DevOps engineer interested in creating a complete CI/CD pipeline, I wanted more than a basic "hello world" microservice. I was looking for a project where I could start from scratch – beginning with raw source code, writing my own Docker Compose and Kubernetes files, deploying locally, and then adding automation, environment promotion, and GitOps practices step by step.

In my search, I found several GitHub repositories. Most were either too simple to be useful or too complicated and already set up, leaving no room for learning. They often included ready-made Docker Compose files and Kubernetes manifests, which didn't help with learning through hands-on experience.

That’s when I discovered Craftista, a project maintained by Gourav Shah (gouravshah). This wasn’t just another training repo. As described in its documentation:

β€œCraftista is not your typical hello world app or off-the-shelf WordPress app used in most DevOps trainings. It is the real deal.”

Craftista
Craftista

Craftista stood out to me for several reasons:

  • It’s a polyglot microservices application, designed to resemble a real-world platform.
  • Each service uses its own technology stack – exactly like in modern enterprises.
  • It includes essential building blocks of a real e-commerce system:
    • A modern UI built in Node.js
    • A Product Catalogue Service
    • A Recommendation Engine
    • A Voting/Review Service

By the end of this guide, you won’t just have a β€œhello world” demo – you’ll have a fully functioning CI/CD/GitOps pipeline modeled on a real-world microservices stack. You’ll understand how the pieces fit together, why each tool exists, and how to adapt this workflow to your own projects.

Ready to go beyond hello world and build a production-style pipeline from scratch? Let’s dive in.

Table of Contents

(1/6) Topics Outside the Scope of This Guide (2/6) What is GitOps? (3/6) Tools We Are Using in This Guide (4/6) How to Structure Repositories for Microservice Applications (5/6) How to Organize Kubernetes Manifests for GitOps (6/6) How to Deploy and Promote Your Craftista Microservices Application

Prerequisites and What You’ll Learn:

Before you progress through this guide, ask yourself:

  • Do I understand how semantic tagging improves traceability across environments?
  • Can I replicate a multi-environment GitOps setup using Helm and Kubernetes?
  • Am I confident in organizing Helm charts and manifests for scalable deployments?
  • Do I know how Kargo and Argo CD work together to automate promotions and approvals?

This guide will help you confidently answer those questions by walking you through:

  • βœ… An optimized Git branching strategy: using feature branches and a single main branch
  • βœ… Semantic Docker image tagging for clean version tracking
  • βœ… Helm chart and Kubernetes manifest structuring for multi-environment GitOps
  • βœ… CI pipelines using GitHub Actions for build β†’ test β†’ tag automation
  • βœ… Full GitOps workflows with Kargo and Argo CD for seamless promotion and delivery

Topics Outside the Scope of This Guide

  • Deployment to managed services like EKS, AKS, or GKE is not included. We’ll use Minikube for local development.
  • I assume you are already familiar with writing basic Kubernetes manifests. I won’t explain Pods, Services, Deployments, and their YAML structures here.
  • I also won’t discuss topics like logging, metrics, tracing, and security hardening.
  • This guide does not cover Managing Secrets and ConfigMaps and Implementing Service Discovery.
  • And finally, we won’t go over ArgoCD and Kargo installation.

What is GitOps?

GitOps is a modern way to manage applications and infrastructure using Git as the main source of truth. Developers have used Git for a long time to manage and work together on code. GitOps takes this further by including infrastructure setup, deployment processes, and automation.

By keeping everything – from Kubernetes files and Helm charts to infrastructure code and app settings – in Git, teams have a central, version-controlled system that can be tracked. Changes in Git are automatically updated and matched with the target environments by GitOps tools like Argo CD or Flux.

Core Principles of GitOps

  • Git as the single source of truth
  • Declarative systems
  • Immutable deployments
  • Centralized change audit

Tools We Are Using in This Guide

Tools
Tools

GitHub Actions

GitHub Actions is a platform for continuous integration and delivery (CI/CD) that helps automate your build, test, and deployment processes.

In our project, we’ll use it to store our microservice application code. We’ll use GitHub Actions workflows to build and push Docker images to Docker Hub as our Docker registry. We’ll rely on GitHub Actions for continuous delivery.

Minikube

We are deploying our application and ArgoCD locally on Minikube. To simulate promotion between different environments, I am using namespaces.

Argo CD

Argo CD is a declarative GitOps continuous deployment tool for Kubernetes that automates the deployment and synchronization of microservice applications with Git repositories. It follows GitOps principles and uses declarative configurations with a pull-based approach.

ArgoCD Flow
ArgoCD Flow

Here’s a summary of the flow depicted in the above image:

  1. The developer modifies application code and changes are pushed to a Git repository.
  2. The CI pipeline is triggered and builds a new container image and pushes it to a container registry.
  3. Merge triggers a webhook to notify Argo CD of changes in the Git repository.
  4. Argo CD clones the updated Git repository. Compares the desired state (from Git) with the current state in the Kubernetes cluster.
  5. Argo CD applies the necessary changes to bring the cluster to the desired state.
  6. Kubernetes controllers reconcile resources until the cluster matches the desired configuration.
  7. Argo CD continuously monitors the application and cluster state.
  8. Argo CD can automatically or manually revert the changes to match the Git configuration, ensuring Git remains the single source of truth.

Kargo

Kargo manages promotion by watching repositories (Git, Image, Helm) for changes and making the needed commits to your Git repository, while Argo CD takes care of reconciliation. Kargo is built to simplify multi-stage application promotion using GitOps principles, removing the need for custom automation or CI pipelines.

Kargo (Source: Akuity Blog)
Kargo (Source: Akuity Blog)

Kargo Components

  1. Warehouse: Watches image registries and discovers new container images. Monitors DockerHub for new tags like v1.2.0, v1.2.1, etc., and stores metadata about discovered images.
  2. Stage: Defines a deployment environment (Dev, Stage, Prod). When a new image is found by the warehouse, it updates the manifest under env/dev/ with the new image tag. This triggers Argo CD to sync the dev environment.
  3. PromotionPolicy: Defines how promotion should happen between stages (for example, auto or manual).
  4. Freight: An artifact version to be promoted (for example, a specific container image or Helm chart). When v1.2.1 is discovered by the warehouse, a new Freight is created.
Kargo Components
Kargo Components

Practical Examples

  • A new v1.2.0 image is pushed to DockerHub.
  • Kargo detects it via a warehouse and updates the dev environment.
  • Once verified (either by tests or metrics), Kargo automatically updates Helm values in the Git repo for staging.
  • Argo CD sees the Git change and syncs the new version to staging.
  • Manual approval (via Slack or UI) is required to push to production.

Why Kargo is the Perfect Companion to Argo CD

Have you ever had to manually promote versions across environments and wished it were automated? How would integrating Kargo have saved time or prevented errors in your last deployment?

Argo CD excels at GitOps-driven continuous deployment – syncing your Kubernetes cluster with the desired state declared in Git. But it lacks native support for promotion workflows between environments (like dev β†’ staging β†’ production) based on image metadata, test results, or approval gates. This is where Kargo becomes the perfect companion.

Kargo and Argo CD Comparison
Kargo and Argo CD Comparison

Kargo doesn’t replace Argo CD – it extends it. You continue to use Argo CD for syncing and deploying apps, but Kargo adds promotion intelligence and automation.

How to Structure Repositories for Microservice Applications

My example application consists of 4 microservices (frontend (nitheeshp-irl/microservice-frontend), recommendation (nitheeshp-irl/microservice-recommendation), catalogues (nitheeshp-irl/microservice-catalogue), and voting (nitheeshp-irl/microservice-voting)). Designing your repository structure is very important to start your project. There is a lot of debate between monorepo and multi-service repo.

A monorepo is a unified repository that houses all the code for a project or a set of related projects. It consolidates code from various services, libraries, and applications into a single centralized location.

On the other hand, a polyrepo architecture comprises multiple repositories, each containing the code for a distinct service, library, or application component.

Why a Polyrepo Fits My Microservice-Service App

Imagine you're onboarding a new team to your app. Would you prefer giving them access to an entire monorepo or just the relevant service’s repo? What trade-offs are you willing to accept?”

Well, using a polyrepo approach,

  • Teams can work independently on the frontend, recommendations, catalogs, and voting without stepping on each other’s toes.
  • Sensitive services remain locked down without complex directory-level rules.
  • CI runners operate on a smaller codebase, speeding up checkouts and reducing bandwidth.
  • Each service has its own release cadence (for example, catalogues v2.1.0 and voting v1.7.3).
  • As your organization grows, new teams can onboard to only the repos they care about.
  • Shared libraries can be versioned and published to an internal package registry, then consumed by each service.

Git Branching is Anti Pattern to GitOps Principles

Git Branching AntiPattern
Git Branching AntiPattern

Many teams default to β€œGitFlow (novai-devops-101)”-style branching – creating long-lived branches for dev, staging, prod, and more. But in a true GitOps workflow, Git is your control plane, and β€œenvironments” shouldn’t live as branches.

Instead, you can keep things simple with just:

  • A long-lived master (or main) branch
  • Short-lived feature branches for code work

How to Organize Kubernetes Manifests for GitOps

This repo (nitheeshp-irl/microservice-helmcharts) shows how you can keep ArgoCD application manifests, environment-specific values, Kargo promotion tasks, Helm charts for each microservice, and CI/CD workflows all in one place. It is organized so that:

  1. ArgoCD application manifests live under argocd/, split by environment (for example, dev/, staging/, prod/).
  2. Environment-specific overrides (Helm values or Kustomize patches) go under env/.
  3. Kargo promotion configurations are grouped under kargo/, defining how new images move between environments.
  4. Service Helm charts reside in service-charts/, one chart per microservice.

Argo CD Folders

The argocd/ directory contains all of the manifests that Argo CD needs in order to track, group, and deploy your microservices. In this guide, we break that directory into two main pieces:

  1. Argo CD Project Definition
  2. Argo CD Application Manifests (organized by environment)

ArgoCD Projects

Projects - Argo CD - Declarative GitOps CD for Kubernetes
Projects provide a logical grouping of applications, which is useful when Argo CD is used by multiple teams. Projects provide the following features...

Before you can give Argo CD a set of Applications to manage, it’s often best practice to define a β€œProject.” A Project in Argo CD serves as a logical boundary around a group of Applications. It can control which Git repos those Applications are allowed to reference, which Kubernetes clusters/namespaces they can target, and even which resource kinds they can manage.

In our example repo, the file craftisia-project.yaml lives at the top of argocd/:

2. Argo CD Application Manifests (by Environment)

Inside argocd/, there is a subdirectory called application/. We use this to keep all of our Argo CD Application YAMLs, broken out by environment. The high-level layout looks like this:

rCopyEditargocd/
└── application/
    β”œβ”€β”€ dev/            # β€œDev” environment Applications
    β”‚   β”œβ”€β”€ catalogue.yaml
    β”‚   β”œβ”€β”€ catalogue-db.yaml
    β”‚   β”œβ”€β”€ frontend.yaml
    β”‚   β”œβ”€β”€ recommendation.yaml
    β”‚   β”œβ”€β”€ voting.yaml
    β”‚   └── kustomization.yaml
    β”œβ”€β”€ staging/        # β€œStaging” environment Applications (same names/structure as dev/)
    β”‚   └── […]
    └── prod/           # β€œProd” environment Applications (same names/structure as dev/)
        └── […]

Each of those YAML files is a standalone Argo CD Application. An Application tells Argo CD:

  1. Which project it belongs to (in our case, craftisia),
  2. Where to find its manifests (a Git repo and path),
  3. Which Kubernetes cluster and namespace to deploy into, and
  4. How to keep itself up to date (that is, sync policies).

Below is a example of the frontend.yaml file for the dev environment:

You would repeat a similar pattern under argocd/application/staging/ and argocd/application/prod/ – each environment has its own frontend.yaml, catalogue.yaml, and so on, but each will point to a different values file under env/staging/… or env/prod/… and likely deploy into a different namespace (for example, front-end-staging, front-end-prod).

Env Folders

The /env directory is a critical part of our GitOps implementation, containing all environment-specific configurations for our microservices. Each environment (dev, staging, prod) has its own subdirectory containing service-specific configurations. These contain general Helm chart values like resource limits and replica counts and container image repository and tag.

image:
  repository: nitheesh86/microservice-frontend
  tag: 1.0.11

replicaCount: 2

resources:
  limits:
    memory: "512Mi"
  requests:
    cpu: "100m"
    memory: "128Mi"

Kargo Folders

Our Kargo setup is organized in the /kargo directory with several key components:

/kargo/
β”œβ”€β”€ catalogue-config/           # Catalogue service promotion configuration
β”‚   β”œβ”€β”€ catalogue-promotion-tasks.yaml  # Defines how to update catalogue images
β”‚   β”œβ”€β”€ catalogue-stages.yaml           # Dev, staging, prod stages for catalogue
β”‚   └── catalogue-warehouse.yaml        # Monitors catalogue image repository
β”œβ”€β”€ frontend-config/            # Frontend service promotion configuration
β”‚   β”œβ”€β”€ frontend-promotion-tasks.yaml   # Defines how to update frontend images
β”‚   β”œβ”€β”€ frontend-stages.yaml            # Dev, staging, prod stages for frontend
β”‚   └── frontend-warehouse.yaml         # Monitors frontend image repository
β”œβ”€β”€ recommendation-config/      # Recommendation service promotion configuration
β”‚   β”œβ”€β”€ recommendation-promotion-tasks.yaml  # Image update workflow
β”‚   β”œβ”€β”€ recommendation-stages.yaml           # Environment stages
β”‚   └── recommendation-warehouse.yaml        # Image monitoring
β”œβ”€β”€ voting-config/              # Voting service promotion configuration
β”‚   β”œβ”€β”€ voting-promotion-tasks.yaml     # Image update workflow
β”‚   β”œβ”€β”€ voting-stages.yaml              # Environment stages
β”‚   └── voting-warehouse.yaml           # Image monitoring
β”œβ”€β”€ kargo.yaml                  # ArgoCD application for Kargo installation
β”œβ”€β”€ kustomization.yaml          # This file - combines all resources
β”œβ”€β”€ project.yaml                # Defines the Kargo project
└── projectconfig.yaml          # Project-wide promotion policies

Stage Configurations: Kargo uses the concept of "stages" to represent our deployment environments. Each stage defines:

  • Which freight (container images) to deploy
  • The promotion workflow to execute
  • Environment-specific variables

Warehouse Configuration: The warehouse monitors our container registry for new images.

Promotion Tasks: Promotion tasks define the actual workflow for promoting between environments.

How to Deploy and Promote Your Craftista Microservices Application

Now I'll explain how to deploy your Craftista microservices application using Argo CD.

ArgoCD Dashboard
ArgoCD Dashboard

Prerequisites

  • A local Kubernetes cluster: We’ll use Minikube for local development.
  • kubectl and helm: Ensure both are installed and configured.
  • Git Clone of the microservice-helmcharts Repo:
git clone https://github.com/nitheeshp-irl/microservice-helmcharts.git
cd microservice-helmcharts

1. Start Minikube

Start Minikube with the specified resources:

minikube start --memory=4096 --cpus=2
kubectl config use-context minikube

Adjust --memory and --cpus as needed for your machine.

2. Install Argo CD

Create a namespace:

kubectl create namespace argocd

Apply the official install manifest:

kubectl apply -n argocd \
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

3. Access the Argo CD UI

Port-forward the server:

kubectl port-forward svc/argocd-server \
-n argocd 8080:443

Login:

  • Username: admin
  • Password:
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d

Open your browser at http://localhost:8080.

4. Define a β€œCraftista” Argo CD Project

Scope Repos, Clusters, and Namespaces:

kubectl apply -f argocd/application/craftista-project.yaml
#
# project.argoproj.io/craftista created

5. Deploy the Development Environment

Create Argo CD applications:

kubectl apply -f argocd/application/dev/

Argo CD will:

  • Clone the microservice-helmcharts repo.
  • Render each Helm chart with its env/dev/*-values.yaml.
  • Create Deployment, Service, and so on in your dev namespaces.
  • Continuously reconcile desired vs. actual state.

Monitor your progress:

argocd app list
argocd app get frontend-dev

6. Manual Promotion (Staging & Prod)

Edit the image tag or other values:

  • env/staging/<service>/<service>-values.yaml
  • env/prod/<service>/<service>-values.yaml

Commit and push the changes:

git add env/staging env/prod
git commit -m "Promote v1.2.0 β†’ staging & prod"
git push

Argo CD will detect the Git change and automatically sync your staging and prod applications (if automated sync is enabled).

7. Automated Promotion with Kargo

Kargo DashBoard
Kargo DashBoard

First, install Kargo:

kubectl apply -f kargo/kargo.yaml

Configure promotion tasks, stages, and warehouse:

kubectl apply -k kargo/
# 
# apiVersion: kustomize.config.k8s.io/v1beta1
# kind: Kustomization
# 
# resources:
#   - project.yaml
#   - projectconfig.yaml
#   - catalogue-config/catalogue-warehouse.yaml
#   - catalogue-config/catalogue-stages.yaml
#   - catalogue-config/catalogue-promotion-tasks.yaml
#   - frontend-config/frontend-warehouse.yaml
#   - frontend-config/frontend-stages.yaml
#   - frontend-config/frontend-promotion-tasks.yaml
#   - recommendation-config/recommendation-warehouse.yaml
#   - recommendation-config/recommendation-stages.yaml
#   - recommendation-config/recommendation-promotion-tasks.yaml
#   - voting-config/voting-warehouse.yaml
#   - voting-config/voting-stages.yaml
#   - voting-config/voting-promotion-tasks.yaml

How the GitOps Pipeline Works

  1. Developer Opens a Pull Request: The journey begins when a developer opens a pull request on one of the microservice repos. This signals that new code (feature, bugfix, config change) is ready to be integrated.
  2. CI (GitHub Actions)
    • CI: Lint β†’ Test β†’ Build & Tag: A single workflow job lints the code, runs unit/integration tests, builds the Docker image, and applies a semantic tag (for example, v1.2.0).
    • CI OK? (Decision):
      • If No, the pipeline stops and the developer is notified to fix errors.
      • If Yes, the newly built image is pushed to the container registry (DockerHub, ECR, and so on).
  3. Kargo
    • Warehouse discovers new image tag: Kargo’s Warehouse component continuously watches your registry. As soon as it sees the new tag, it records that image metadata.
    • Update env/dev values β†’ Git: Kargo automatically commits an update to env/dev/<service>/…-values.yaml, pointing the dev Helm values file to the new image tag. This Git commit will drive the next step.
  4. GitOps (Argo CD)
  5. Argo CD sync dev: Argo CD sees the Git change in the dev values file and pulls it into the cluster, reconciling the actual dev namespace with the desired state.
    • Dev deployment healthy? (Decision):
      • If No, Argo CD can optionally roll back and notifies the team (via Slack, email, etc.) of the failed dev rollout.
      • If Yes, it’s time to promote to staging.
    • Update env/staging values β†’ Git: Kargo (or you, if manual) commits the same image tag into env/staging/<service>/…-values.yaml.
      • Argo CD sync staging: Argo CD deploys that change to the staging namespace.
      • Staging approval granted? (Decision):
        • If No, Kargo waits (and optionally notifies) until a manual gate is lifted.
        • If Yes, the final promotion commit is made: updating env/prod/<service>/…-values.yaml.
      • Argo CD sync prod β†’ End: Argo CD applies the production change, completing the pipeline from commit all the way to live production rollout.

Pipeline Summary

  1. Developer opens PR β†’ CI tests and builds β†’ Docker image pushed
  2. Kargo Warehouse detects new tag β†’ Git commit to env/dev
  3. Argo CD syncs dev β†’ Health check β†’ (if successful) commit to env/staging
  4. Argo CD syncs staging β†’ Approval β†’ commit to env/prod
  5. Argo CD syncs prod β†’ Live deployment complete

Every stage must pass its health or approval check before the next begins, ensuring that only thoroughly tested and validated code makes it into production.

Conclusion

Building a real-world CI/CD pipeline isn’t just about getting code from your laptop into a Kubernetes cluster – it’s about creating a repeatable, auditable, and reliable system that scales with your team and your application complexity.

In this guide, we walked through how I built a complete GitOps-based promotion pipeline using GitHub Actions, Argo CD, and Kargo, all driven by a hands-on microservices project: Craftista. From the first code commit to automated environment promotion, we leveraged industry best practices like semantic versioning, declarative infrastructure, and environment-based GitOps directories.

What makes this approach powerful is not just the tools but also the principles. By treating Git as the single source of truth, and using Kargo to automate what was traditionally a manual and fragile promotion process, we gain predictability and control over our deployments. Argo CD ensures that what’s in Git is always what’s running in our clusters, while Kargo eliminates human error in multi-stage rollouts.

If you’re tired of overly abstract β€œhello world” DevOps tutorials and want to get your hands dirty with something that feels real, Craftista offers the perfect sandbox. This pipeline reflects how teams operate in production – polyglot services, independent deployments, environment promotion gates, and GitOps as the operational backbone.

Whether you're a DevOps engineer sharpening your skills, or a platform team setting standards for internal development, I hope this tutorial provided the clarity and inspiration to build your own commit-to-production pipeline – step by step, with confidence.

Further Reading & Resources

Argo CD - Declarative GitOps CD for Kubernetes
Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes.
Home | Kargo Docs
Learn how to use Kargo for GitOps promotions
GitHub Actions documentation - GitHub Docs
Automate, customize, and execute your software development workflows right in your repository with GitHub Actions. You can discover, create, and share actions to perform any job you'd like, including CI/CD, and combine actions in a completely customized workflow.
How to Model Your GitOps Environments and Promote Releases between Them
Learn how to model your GitOps environments using different folders on the same Git branch, and how to handle environment promotion.
craftista/craftista
Craftista - The Origami Store is a Devops Learning App created by School of Devops.
From Commit to Production: Hands-On GitOps Promotion with GitHub Actions, Argo CD, Helm, and Kargo
Have you ever wanted to go beyond β€˜hello world’ and build a real, production-style CI/CD pipeline – starting from scratch? Let’s pause for a moment: what are you trying to learn from your DevOps journey? Are you focusing on GitOps-style deployments, ...
MIT Licensed | Copyright Β© 2022-present Chan Hee Lee
Copyright Β© 2025 Nitheesh Poojary