# How to Integrate Argo CD with CI/CD Pipelines: A Complete GitOps Guide

> Learn to integrate Argo CD with CI/CD pipelines. Push manifest updates to Git and trigger automated deployments for a seamless GitOps workflow. Deploy faster with Argo CD.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-09

---

**Integrate Argo CD with CI/CD pipelines by having your build pipeline push updated Kubernetes manifests to Git, then either trigger an explicit sync via the `argocd` CLI or configure automatic synchronization to deploy changes without additional API calls.**

Argo CD follows the GitOps model where Git repositories serve as the single source of truth for cluster state. To integrate Argo CD with CI/CD pipelines effectively, you separate the build and manifest generation concerns from the deployment orchestration, letting the pipeline update Git while Argo CD handles the actual cluster synchronization.

## The GitOps Integration Pattern

The standard integration pattern decouples artifact creation from deployment. Your CI/CD pipeline performs build and template operations, while Argo CD manages the reconciliation between Git and the live cluster. This approach ensures **idempotent deployments**—since the source of truth lives in Git, re-running the same pipeline step does not create duplicate resources. Argo CD detects that the desired state already matches the cluster and applies no changes.

## The Four-Step CI/CD Workflow

A complete integration follows this sequence:

1. **Build & Publish Artifacts** – The pipeline builds a container image and pushes it to a registry (e.g., `ghcr.io/example/app:${GITHUB_SHA}`).

2. **Update Manifests** – Using your templating tool of choice (Kustomize, Helm, or plain YAML patches), the pipeline updates Kubernetes manifests to reference the new artifact version.

3. **Commit & Push** – The updated manifests are committed to the Git repository that Argo CD watches.

4. **Synchronize the Application** – Either through explicit CLI invocation or automated sync policies.

## Explicit Sync vs. Automated Sync

### Explicit Sync via CLI

For pipelines requiring immediate feedback or deployment gates, use the `argocd` CLI to trigger synchronization manually. According to the Argo CD source code in [`cmd/argocd/app.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/app.go), the `argocd app sync` and `argocd app wait` commands provide granular control over the deployment lifecycle.

The pipeline downloads the matching `argocd` binary directly from the API server to guarantee CLI-API compatibility, then authenticates using a **project-scoped JWT token**:

```bash

# Download the CLI binary matching the server version

curl -sSL -o /usr/local/bin/argocd https://${ARGOCD_SERVER}/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

# Generate a project-scoped token for limited access

export ARGOCD_AUTH_TOKEN=$(argocd proj role create-token myproj syncer --client-secret ${CI_SECRET})

# Sync and wait for healthy state

argocd app sync my-app
argocd app wait my-app --health --timeout 300

```

This approach blocks the pipeline until Argo CD reports the application as healthy, enabling immediate rollback if the deployment fails.

### Automated Sync with Webhooks

For simpler workflows, configure the Application resource with an automated sync policy. As implemented in [`controller/appcontroller.go`](https://github.com/argoproj/argo-cd/blob/main/controller/appcontroller.go), the reconciliation loop watches for Git commits and triggers sync operations automatically when `syncPolicy.automated` is enabled:

```yaml
syncPolicy:
  automated:
    prune: true
    selfHeal: true

```

In this mode, the pipeline omits the CLI sync commands. Argo CD detects the new commit via webhook or polling (default interval approximately 3 minutes) and applies changes automatically. This reduces pipeline complexity and eliminates the need to manage API tokens in your CI environment.

## Authentication and Security

Secure your CI/CD integration using **project-scoped JWT tokens** rather than global admin credentials. Generated via `argocd proj role create-token`, these tokens limit the scope to a single project's sync operations. If the token is compromised, the blast radius remains confined to specific applications rather than the entire cluster.

## Complete Pipeline Example

This bash script demonstrates the full workflow in a GitHub Actions environment:

```bash

# 1️⃣ Build & push the container image

docker build -t ghcr.io/example/app:${GITHUB_SHA} .
docker push ghcr.io/example/app:${GITHUB_SHA}

# 2️⃣ Update the manifest using a plain YAML patch

git clone https://github.com/example/app-manifests.git
cd app-manifests
kubectl patch --local -f deployment.yaml \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","image":"ghcr.io/example/app:'${GITHUB_SHA}'"}]}}}}' \
  -o yaml > deployment.yaml

# 3️⃣ Commit the changes

git commit -am "Update app image to ${GITHUB_SHA}"
git push origin main

# 4️⃣ Explicit sync (omit if using automated syncPolicy)

export ARGOCD_SERVER=${ARGOCD_HOST}
export ARGOCD_AUTH_TOKEN=$(argocd proj role create-token myproj syncer --client-secret ${CI_SECRET})
curl -sSL -o /usr/local/bin/argocd https://${ARGOCD_SERVER}/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
argocd app sync my-app
argocd app wait my-app --health --timeout 300

```

## Key Source Files and Implementation Details

The Argo CD repository contains specific implementations that power this integration:

- **[`cmd/argocd/app.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/app.go)** – Implements the `argocd app sync` and `argocd app wait` commands used by pipelines for explicit synchronization.
- **[`controller/appcontroller.go`](https://github.com/argoproj/argo-cd/blob/main/controller/appcontroller.go)** – Contains the reconciliation loop that watches Git commits and triggers automatic sync operations when `syncPolicy.automated` is enabled.
- **[`docs/user-guide/ci_automation.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/ci_automation.md)** – Documents the CI automation workflow, including image build patterns and CLI-based sync strategies.
- **[`docs/user-guide/auto_sync.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/auto_sync.md)** – Details the configuration options for automatic synchronization without explicit CLI calls.
- **[`docs/user-guide/best_practices.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/best_practices.md)** – Discusses repository separation patterns, recommending distinct repositories for application source code and deployment manifests.

## Summary

- **GitOps separation**: Keep CI pipelines responsible for building and pushing manifest updates to Git, while Argo CD handles the actual cluster synchronization.
- **Two sync strategies**: Choose **explicit CLI sync** (`argocd app sync/wait`) for deployment gates and immediate feedback, or **automated sync** for hands-off continuous deployment.
- **Security**: Use project-scoped JWT tokens generated via `argocd proj role create-token` to limit CI pipeline permissions.
- **Rollback capability**: Revert commits in Git to trigger automatic rollbacks, or use `argocd app rollback <app> <revision>` from the pipeline.
- **Speed**: Webhook-triggered auto-sync typically deploys changes within seconds, while polling mode defaults to approximately 3-minute intervals.

## Frequently Asked Questions

### How does Argo CD prevent duplicate deployments when CI pipelines re-run?

Argo CD maintains idempotency because Git serves as the source of truth. When a pipeline re-runs and pushes the same manifest commit, the reconciliation loop in [`controller/appcontroller.go`](https://github.com/argoproj/argo-cd/blob/main/controller/appcontroller.go) detects that the desired state already matches the live cluster state and applies no changes. Duplicate resources are never created because the Git commit hash remains identical.

### What is the difference between `argocd app sync` and automated synchronization?

**Explicit sync** requires the CI pipeline to call `argocd app sync <app>` and optionally `argocd app wait <app>` (implemented in [`cmd/argocd/app.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/app.go)), blocking the pipeline until the deployment completes. **Automated sync** configures the Application with `syncPolicy.automated: true`, allowing Argo CD to detect Git changes via webhooks or polling and apply them without CI intervention.

### How do I authenticate CI pipelines with Argo CD securely?

Generate a **project-scoped JWT token** using `argocd proj role create-token <project> <role>` rather than using global admin credentials. This limits the token's permissions to specific applications within that project. The CI pipeline exports this token as `ARGOCD_AUTH_TOKEN` and downloads the matching `argocd` CLI binary from the API server to ensure version compatibility.

### Can I rollback a deployment if the CI pipeline pushes a bad commit?

Yes. If automated sync is enabled, simply revert the problematic commit in Git and Argo CD will automatically roll back the cluster to the previous state. Alternatively, from the CI pipeline, execute `argocd app rollback <app> <revision>` to revert to a specific historical version without modifying the Git repository.