How To Migrate To A GitOps Workflow With Helm, OpenShift, And ArgoCD

|

The way organizations manage applications and infrastructure has dramatically shifted in recent years. Traditional manual deployments have given way to automation-driven approaches, ensuring consistency, reproducibility, and faster delivery cycles. Among these approaches, GitOps has emerged as a modern operational framework that applies DevOps best practices to infrastructure automation.

GitOps leverages Git repositories as the single source of truth for declarative infrastructure and applications. When combined with tools like Helm, OpenShift, and ArgoCD, GitOps provides a powerful workflow for automating application lifecycle management across environments.

In this article, we will dive deep into how to migrate to a GitOps workflow using Helm, OpenShift, and ArgoCD, complete with examples, practices, and a structured step-by-step approach.

Understanding GitOps

Before implementing GitOps, it’s important to understand what it entails.

GitOps revolves around four core principles:

  1. Declarative Descriptions – All system components (infrastructure, apps, policies) are declared as code in Git.

  2. Single Source of Truth – Git is the canonical source of what should be running in your environments.

  3. Automated Delivery – A Git push triggers automated reconciliation processes to align cluster state with Git state.

  4. Continuous Reconciliation – An operator continuously monitors live environments and ensures they match the Git-defined state.

By adopting GitOps, teams gain consistency, observability, and traceability across deployments.

Why Helm, OpenShift, and ArgoCD?

When building a GitOps workflow, the combination of Helm, OpenShift, and ArgoCD stands out for several reasons:

  • Helm simplifies Kubernetes deployments by packaging apps into reusable charts, making it easier to manage complex applications.

  • OpenShift provides an enterprise-ready Kubernetes platform with additional features like built-in CI/CD, security, and developer tools.

  • ArgoCD acts as the GitOps operator, ensuring that the desired state in Git matches the cluster’s actual state by automating synchronization and rollback.

This trio ensures that applications are not only reproducible but also secure and manageable at scale.

Preparing Your Environment

To migrate to GitOps, ensure your environment has the following components set up:

  1. OpenShift Cluster – Either on-premises or on a cloud provider.

  2. Helm CLI – For managing Helm charts locally before pushing to Git.

  3. ArgoCD Installed on OpenShift – To monitor repositories and sync states.

  4. Git Repository – The central hub where your deployment manifests or Helm charts will live.

Example installation for Helm (locally):

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

For OpenShift, you’ll typically already have the cluster running, and you can log in using the oc CLI:

oc login --server=https://api.cluster.example:6443 --token=<your-token>

Installing ArgoCD in OpenShift (using the OpenShift GitOps operator):

oc apply -f https://operatorhub.io/install/openshift-gitops.yaml

Once installed, you can access the ArgoCD UI from the OpenShift console.

Structuring Your Git Repository

A GitOps repository must be well-structured to enable automation. There are two popular approaches:

  • App of Apps Pattern: A parent application defines child applications in ArgoCD, each pointing to its own repo or folder.

  • Environment-Based Structure: Different branches or directories for environments like dev, staging, and prod.

Example repository structure:

├── environments
│ ├── dev
│ │ └── values-dev.yaml
│ ├── staging
│ │ └── values-staging.yaml
│ └── prod
│ └── values-prod.yaml
└── charts
└── my-app
├── Chart.yaml
├── values.yaml
├── templates
│ ├── deployment.yaml
│ ├── service.yaml
│ └── ingress.yaml

This structure allows you to reuse the same Helm chart across multiple environments, with environment-specific overrides.

Creating a Helm Chart

Helm charts package Kubernetes manifests into reusable templates. Let’s create a sample chart for a basic application.

helm create my-app

This generates a folder structure with default templates. For example, your Deployment template (templates/deployment.yaml) may look like this:

apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}-deployment
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
app: {{ .Release.Name }}
template:
metadata:
labels:
app: {{ .Release.Name }}
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
ports:
- containerPort: 8080

And in values.yaml, you might define:

replicaCount: 2
image:
repository: my-dockerhub-user/my-app
tag: "1.0.0"

To deploy locally (before GitOps):

helm install my-app ./my-app -n dev

Configuring ArgoCD To Use Helm

Now that the chart exists in your Git repo, you need to configure ArgoCD to use it.

First, create an ArgoCD application manifest (let’s call it my-app-argo.yaml):

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
namespace: openshift-gitops
spec:
project: default
source:
repoURL: 'https://github.com/your-org/gitops-repo.git'
targetRevision: main
path: charts/my-app
helm:
valueFiles:
- ../../environments/dev/values-dev.yaml
destination:
server: 'https://kubernetes.default.svc'
namespace: dev
syncPolicy:
automated:
prune: true
selfHeal: true

Apply the manifest:

oc apply -f my-app-argo.yaml

ArgoCD will now continuously monitor the repo and deploy/update the application whenever changes are pushed to Git.

Managing Multiple Environments

One of the strongest advantages of GitOps with Helm and ArgoCD is managing multiple environments seamlessly.

Let’s say you have three environments: dev, staging, and prod. Each environment uses the same Helm chart but different values files.

Example: values-prod.yaml

replicaCount: 5
image:
repository: my-dockerhub-user/my-app
tag: "2.0.0"
resources:
limits:
cpu: "1"
memory: "512Mi"

You can create separate ArgoCD applications for each environment, all pointing to the same chart but different values files.

For example, my-app-prod-argo.yaml would look similar but reference values-prod.yaml.

Testing the GitOps Workflow

At this stage, the workflow looks like this:

  1. Developer pushes code changes → CI pipeline builds the image and updates the Helm chart values (image tag).

  2. Git repository is updated → ArgoCD detects the change automatically.

  3. ArgoCD syncs cluster state → OpenShift deploys the updated Helm release.

  4. Cluster reconciles continuously → Any manual drift (e.g., if someone changes replicas directly) is corrected.

You can test by editing values-dev.yaml and changing replicaCount:

replicaCount: 4

Commit and push:

git add .
git commit -m "Increase replicas to 4 for dev"
git push origin main

Within seconds, ArgoCD will notice the change and update the deployment in OpenShift.

Handling Secrets Securely

A major concern in GitOps is managing sensitive data. Storing secrets in plain Git is risky.

There are multiple ways to manage this:

  • Sealed Secrets (Bitnami): Encrypt secrets before committing them.

  • External Secret Operators: Pull secrets dynamically from a vault (e.g., HashiCorp Vault, AWS Secrets Manager).

  • OpenShift Vault Integration: Use Kubernetes-native secret management with restrictions.

Example using Sealed Secrets:

kubeseal < secret.yaml > sealed-secret.yaml

Commit sealed-secret.yaml safely to Git, and only the cluster can decrypt it.

Scaling and Advanced Features

Once the basic workflow is established, you can enhance it with:

  • ApplicationSets in ArgoCD – Automatically generate multiple applications from templates.

  • Progressive Delivery – Integrate with tools like Argo Rollouts for canary and blue-green deployments.

  • Monitoring & Alerts – Use OpenShift Monitoring stack or integrate ArgoCD with Prometheus/Grafana for visibility.

Example ApplicationSet for multiple environments:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: my-app-multi-env
spec:
generators:
- list:
elements:
- env: dev
values: environments/dev/values-dev.yaml
- env: prod
values: environments/prod/values-prod.yaml
template:
metadata:
name: 'my-app-{{env}}'
spec:
source:
repoURL: 'https://github.com/your-org/gitops-repo.git'
targetRevision: main
path: charts/my-app
helm:
valueFiles:
- '{{values}}'
destination:
server: 'https://kubernetes.default.svc'
namespace: '{{env}}'
syncPolicy:
automated:
prune: true
selfHeal: true

This eliminates the need to define multiple Application manifests manually.

Common Pitfalls To Avoid

While migrating, keep in mind some pitfalls:

  1. Mixing Manual and GitOps Changes – Always let Git be the single source of truth. Manual oc or kubectl edits cause drift.

  2. Poor Repository Structure – Disorganized repos make scaling GitOps painful.

  3. Secrets Mismanagement – Never store plain secrets in Git.

  4. Ignoring Rollback Strategy – Ensure Helm and ArgoCD can revert to previous versions in case of failure.

  5. Underestimating Resource Quotas – Different environments may have varying capacity needs; always test with realistic values.

Conclusion

Migrating to a GitOps workflow with Helm, OpenShift, and ArgoCD transforms how teams deliver and manage applications. By making Git the source of truth, organizations gain consistency, reliability, and automation across environments. Helm charts enable reusability and flexibility, while ArgoCD ensures continuous reconciliation between the desired and actual state.

The migration involves several steps: setting up the environment, structuring the Git repository, creating Helm charts, configuring ArgoCD applications, and managing multiple environments. Adding secret management and scaling strategies further strengthens the workflow.

The key benefits include:

  • Auditability: Every change is traceable in Git.

  • Scalability: Easily manage multiple apps and environments.

  • Resilience: Continuous reconciliation ensures system health.

  • Speed: Developers focus on code, while GitOps automates deployments.

Adopting GitOps is not just a tooling change; it’s a cultural shift that enforces discipline and accelerates software delivery. With Helm providing flexibility, OpenShift ensuring enterprise-grade Kubernetes, and ArgoCD automating reconciliation, your team will be well-equipped to deliver reliable and scalable applications in a modern cloud-native world.