DEV Community

Pete Miloravac
Pete Miloravac

Posted on • Originally published at semaphore.io on

Semaphore ArgoCD Integration: Complete Guide with Flux and Terraform

#productnews

If you’re implementing Semaphore ArgoCD integration , you’re building a modern, GitOps-driven CI/CD pipeline for Kubernetes. This guide shows exactly how Semaphore works with ArgoCD, and how Flux and Terraform fit into the same workflow for scalable, production-ready delivery.

You’ll learn:

  • How Semaphore ArgoCD integration works step by step
  • How to design a GitOps CI/CD pipeline
  • Where Flux and Terraform fit in
  • Best practices and common pitfalls

What Is Semaphore ArgoCD Integration?

Semaphore ArgoCD integration means using Semaphore for CI (build, test, validate) and ArgoCD for CD (deploy via GitOps).

  • Semaphore → CI and pipeline orchestration
  • ArgoCD → GitOps-based Kubernetes deployments
  • Flux (optional) → Alternative GitOps CD with automation
  • Terraform → Infrastructure provisioning (IaC)

This separation ensures:

  • Git as the single source of truth
  • Safer deployments
  • Full auditability

How Semaphore ArgoCD Integration Works

In a GitOps model, Semaphore never deploys directly to Kubernetes.

Instead, it updates a Git repository that ArgoCD continuously reconciles.

Developer pushes code
   ↓
Semaphore (CI pipeline)
   ↓
Build + Test + Push Docker image
   ↓
Update Git (Kubernetes manifests)
   ↓
ArgoCD detects changes
   ↓
Deploy to Kubernetes
Enter fullscreen mode Exit fullscreen mode

This is the core of Semaphore ArgoCD integration.

Semaphore ArgoCD Integration Workflow (Step-by-Step)

  1. Run tests in Semaphore
  2. Build and tag Docker image
  3. Push image to registry
  4. Update Kubernetes manifests in Git
  5. ArgoCD syncs and deploys automatically

Example: Updating manifests from Semaphore 

git clone git@github.com:org/k8s-config.git
cd k8s-config
sed -i "s|image: app:.*|image: app:${SEMAPHORE_GIT_SHA}|" deployment.yaml

git commit -am "Deploy ${SEMAPHORE_GIT_SHA}"
git push
Enter fullscreen mode Exit fullscreen mode

Why this integration pattern works

  • Enforces GitOps principles
  • Keeps CI and CD cleanly separated
  • Enables easy rollback via Git
  • Improves security and traceability

Semaphore ArgoCD Integration vs Flux (GitOps Alternative)

Flux provides a similar GitOps approach with additional automation.

Option 1: Semaphore updates manifests 

kustomize edit set image app=repo/app:${SEMAPHORE_GIT_SHA}
git commit -am "Update image"
git push
Enter fullscreen mode Exit fullscreen mode

Option 2: Flux Image Automation

  • Semaphore builds and pushes images
  • Flux automatically updates manifests

When to use Flux instead of ArgoCD

  • You want automated image updates
  • You prefer controller-driven workflows

Using Terraform with Semaphore ArgoCD Integration

Terraform complements Semaphore ArgoCD integration by managing infrastructure.

Typical Terraform workflow in Semaphore 

terraform init
terraform plan -out=tfplan
terraform apply -auto-approve tfplan
Enter fullscreen mode Exit fullscreen mode

Best practices

  • Use remote state
  • Add approval gates for production
  • Separate infra and app pipelines

End-to-End Pipeline with Semaphore ArgoCD Integration

  1. Developer pushes code
  2. Semaphore runs CI pipeline
  3. Image is built and pushed
  4. GitOps repo is updated
  5. ArgoCD deploys to Kubernetes
  6. Terraform runs if needed

Benefits

  • Fully Git-driven deployments
  • Clear separation of responsibilities
  • High scalability and observability

Common Mistakes in Semaphore ArgoCD Integration

❌ Deploying directly from Semaphore

Breaks GitOps and removes auditability.

❌ Mixing Terraform with app deployments

Creates unnecessary coupling.

❌ Skipping approval gates

Leads to unsafe production changes.

Best Practices for Semaphore ArgoCD Integration

  • Use Git as the source of truth
  • Keep CI and CD separate
  • Automate builds, not deployments
  • Use Terraform only for infrastructure
  • Version everything

Conclusion: When to Use Semaphore ArgoCD Integration

Semaphore ArgoCD integration is ideal when you want a scalable, GitOps-based CI/CD pipeline for Kubernetes.

  • Semaphore handles CI and orchestration
  • ArgoCD handles deployments
  • Terraform manages infrastructure

Together, they create a reliable, production-ready DevOps platform.

Next Steps

  • Set up a Semaphore CI pipeline
  • Create a GitOps repository for ArgoCD
  • Structure Terraform modules and environments

This setup gives you a strong foundation for modern DevOps.

The post Semaphore ArgoCD Integration: Complete Guide with Flux and Terraform appeared first on Semaphore.

Top comments (0)