Struggling with ArgoCD Rollback? Step-by-Step Guide with CLI, UI & ApplicationSets 2025

Picture this: It’s 2 AM, your production API is throwing 500 errors, and users are flooding your support channels. The culprit? That “quick fix” deployment you pushed an hour ago. Your heart rate spikes as you realize you need to roll back—fast. But wait, ArgoCD’s auto-sync is enabled, your ApplicationSet has multiple sources, and you’re not entirely sure if a simple rollback will stick.

Sound familiar? If you’ve worked with ArgoCD in production environments, you’ve likely faced this scenario or something similar. Rolling back applications in GitOps isn’t just about clicking an “undo” button—it requires understanding how ArgoCD handles revisions, Git state synchronization, and the intricate dance between your desired state in Git and your actual cluster state.

In this comprehensive guide, we’ll dive deep into ArgoCD rollbacks, covering everything from basic UI operations to handling complex edge cases with ApplicationSets and auto-sync conflicts. Whether you’re a seasoned DevOps engineer or new to GitOps, this tutorial will equip you with the knowledge and practical skills to perform safe, reliable rollbacks in any situation.

Why ArgoCD Rollback Mastery Matters in Modern DevOps

ArgoCD has revolutionized how we think about continuous deployment by implementing GitOps principles at scale. However, with great power comes great responsibility—and the occasional need to quickly revert when things go sideways.

Traditional deployment tools often treat rollbacks as an afterthought, but ArgoCD’s GitOps approach introduces unique challenges:

• Git as the source of truth means your rollback strategy must account for both Git history and cluster state
• Auto-sync capabilities can immediately overwrite manual rollbacks if not handled correctly
• Application dependencies and multi-source configurations add complexity to simple rollback operations
• Resource pruning and cleanup require careful consideration to avoid orphaned resources

The stakes are high. A botched rollback can compound your original problem, potentially taking your entire application offline. But a well-executed rollback? It’s your safety net, your get-out-of-jail-free card, and often the difference between a minor incident and a major outage.

How ArgoCD Rollback Works: Core Concepts

Before diving into practical examples, let’s establish a solid understanding of how ArgoCD manages application history and rollbacks.

The Revision History Foundation

ArgoCD maintains a detailed history of every sync operation for each application. This history doesn’t just track Git commits—it captures the complete state of your application at each deployment, including:

• Git commit SHA and associated metadata
• Sync status and any errors encountered
• Resource changes applied during the sync
• Timestamps for audit trails
• Sync policy used (manual vs automatic)

When you perform a rollback, ArgoCD essentially re-applies the Kubernetes manifests from a previous successful sync. This process involves:

1. Retrieving the target revision from the application history
2. Generating manifests from that specific Git commit
3. Applying changes to bring the cluster to the desired previous state
4. Pruning resources if specified (removing resources that existed in current but not in target state)

Understanding the argocd app rollback Command

The CLI command follows this syntax:

argocd app rollback <APPLICATION> <REVISION> [flags]

Key flags you’ll frequently use:

• --prune: Remove resources that don’t exist in the target revision
• --timeout <duration>: Set operation timeout (default: 300s)
• --hard: Force rollback even if there are sync policy conflicts
• --dry-run: Preview what changes would be made without applying them

The revision can be specified as:

• Numeric ID (e.g., 5 for the 5th revision in history)
• Git commit SHA (full or abbreviated)
• HEAD~n notation for relative positioning

Rollback via UI: Step-by-Step Walkthrough

The ArgoCD web interface provides an intuitive way to perform rollbacks, especially useful for teams who prefer visual confirmation of their actions.

Accessing Application History

1. Navigate to your application in the ArgoCD UI
2. Click on the “History and Rollback” tab (usually located in the top navigation of the application view)
3. Review the revision history – you’ll see a chronological list of all sync operations

Each entry in the history displays:

• Revision number and Git commit information
• Sync timestamp and duration
• Sync status (Succeeded, Failed, etc.)
• Initiator (manual sync, auto-sync, or webhook)

Performing the Rollback

1. Identify your target revision – look for the last known good deployment
2. Click the “Rollback” button next to your chosen revision
3. Review the confirmation dialog – it will show:
   • Source and target revisions
   • Potential resource changes
   • Prune settings
4. Confirm the rollback operation

Monitoring Rollback Progress

After initiating the rollback:

1. Watch the sync status in the application overview
2. Monitor the “Events” tab for real-time progress updates
3. Check application health indicators to ensure services are recovering
4. Verify the revision number has changed to your target

Pro tip: Keep your monitoring dashboards open during rollbacks. Application metrics often provide the fastest indication of whether your rollback was successful.

Rollback via CLI: Commands and Real-World Examples

For automation, scripting, and situations where you need granular control, the CLI approach offers superior flexibility.

Basic Rollback Workflow

# First, check your application's current status
argocd app get myapp

# View the revision history
argocd app history myapp

# Example output:
# ID    DATE                           REVISION
# 10    2024-01-15 14:30:22 +0000 UTC  abc123def (HEAD -> main)
# 9     2024-01-15 13:45:18 +0000 UTC  def456ghi
# 8     2024-01-15 12:20:45 +0000 UTC  ghi789jkl
# 7     2024-01-15 11:15:30 +0000 UTC  jkl012mno

# Roll back to revision 8 (known good state)
argocd app rollback myapp 8

# Monitor the rollback progress
argocd app wait myapp --timeout 600

Advanced Rollback Scenarios

Rollback with resource pruning:

# This will remove resources that exist in current but not in target revision
argocd app rollback myapp 7 --prune

Rollback with custom timeout:

# Useful for applications with long startup times
argocd app rollback myapp 6 --timeout 900s

Dry-run rollback for validation:

# Preview changes without applying them
argocd app rollback myapp 5 --dry-run

Scripted Rollback with Validation

Here’s a practical script for automated rollback with health checks:

#!/bin/bash
APP_NAME="myapp"
TARGET_REVISION="$1"

if [ -z "$TARGET_REVISION" ]; then
    echo "Usage: $0 <revision_number>"
    exit 1
fi

echo "Starting rollback of $APP_NAME to revision $TARGET_REVISION..."

# Validate target revision exists
if ! argocd app history $APP_NAME | grep -q "^$TARGET_REVISION"; then
    echo "Error: Revision $TARGET_REVISION not found in history"
    exit 1
fi

# Perform rollback
echo "Executing rollback..."
argocd app rollback $APP_NAME $TARGET_REVISION --timeout 600s

# Wait for sync completion
echo "Waiting for sync completion..."
argocd app wait $APP_NAME --health --timeout 600

# Verify application health
if argocd app get $APP_NAME | grep -q "Health Status:.*Healthy"; then
    echo "✅ Rollback successful - application is healthy"
    exit 0
else
    echo "❌ Rollback completed but application is not healthy"
    exit 1
fi

The Auto-Sync Dilemma: When Rollbacks Fight Git

Here’s where many teams run into trouble: performing a rollback with auto-sync enabled creates a fundamental conflict between your immediate needs and GitOps principles.

Understanding the Conflict

When auto-sync is enabled, ArgoCD continuously monitors your Git repository for changes. After you perform a manual rollback:

1. Rollback succeeds – your application runs the previous version
2. Auto-sync detects “drift” – the cluster state no longer matches Git HEAD
3. Auto-sync re-applies latest Git state – your rollback gets overwritten
4. You’re back to square one – the problematic version is redeployed

This happens because ArgoCD’s auto-sync doesn’t distinguish between intentional rollbacks and unintentional drift.

Strategy 1: Temporary Auto-Sync Disable

The quickest approach for immediate rollbacks:

# Disable auto-sync
argocd app set myapp --sync-policy none

# Perform rollback
argocd app rollback myapp 8

# Wait for rollback completion
argocd app wait myapp --health

# Re-enable auto-sync once you've fixed the issue in Git
argocd app set myapp --sync-policy automated

UI equivalent: In the application settings, toggle off “Auto-Sync” before performing the rollback.

Strategy 2: Git Revert for GitOps Compliance

For a more GitOps-aligned approach, revert the problematic commits in Git:

# In your Git repository
git revert <problematic-commit-sha>
git push origin main

# ArgoCD will auto-sync to the reverted state
# No manual rollback needed

This approach maintains GitOps principles but takes longer and requires Git access.

Strategy 3: Hybrid Approach (Recommended)

Combine immediate rollback with proper Git management:

# 1. Immediate rollback with auto-sync disabled
argocd app set myapp --sync-policy none
argocd app rollback myapp 8

# 2. Fix the issue in Git (revert or patch)
# (Done in parallel by another team member)

# 3. Re-enable auto-sync once Git is fixed
argocd app set myapp --sync-policy automated

This gives you the best of both worlds: immediate relief and proper GitOps hygiene.

Complex Cases and Gotchas

ApplicationSet Rollback Limitations

ApplicationSets introduce additional complexity to rollback scenarios. When working with ApplicationSets:

Multi-source applications may have limited rollback capabilities:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-env-apps
spec:
  generators:
  - list:
      elements:
      - cluster: staging
        revision: main
      - cluster: prod
        revision: release
  template:
    spec:
      sources:
      - repoURL: https://github.com/myorg/app-config
        path: environments/{{cluster}}
      - repoURL: https://github.com/myorg/helm-charts
        chart: myapp

In this scenario, you may need to:

1. Update the ApplicationSet generator to point to a different revision
2. Wait for ApplicationSet controller to reconcile the changes
3. Monitor all generated applications for consistent rollback

Rollback Windows in Argo Rollouts

When using Argo Rollouts alongside ArgoCD, you have additional rollback options:

# Fast rollback using Rollouts (if within rollback window)
kubectl argo rollouts undo rollout myapp-rollout

# This is often faster than full ArgoCD rollback
# as it doesn't regenerate manifests from Git

Handling Partial Rollback Failures

Sometimes rollbacks fail partway through. Common recovery strategies:

# Check what resources are causing issues
argocd app get myapp --show-managed-fields

# Force sync to complete the rollback
argocd app sync myapp --force --replace

# If that fails, manual intervention may be needed
kubectl get pods -n myapp-namespace
kubectl describe pod <failing-pod>

Resource Pruning Complications

Be cautious with --prune flag when:

• Persistent volumes are involved (data loss risk)
• Custom resources have complex deletion logic
• Network policies might affect connectivity during transition

Always test pruning behavior in staging environments first.

Best Practices and Strategic Approaches

1. Implement Atomic Commit Strategies

Structure your Git commits for easy rollbacks:

# Good: Atomic, focused commits
git commit -m "feat: add user authentication endpoint"
git commit -m "fix: resolve memory leak in auth service"

# Bad: Monolithic commits mixing multiple concerns
git commit -m "update auth, fix bugs, add metrics, refactor configs"

2. Tag Stable Releases

Use Git tags to mark known-good states:

# Tag stable releases
git tag -a v1.2.3 -m "Release v1.2.3 - stable"
git push origin v1.2.3

# Easy rollback to tagged versions
argocd app rollback myapp $(argocd app history myapp | grep "v1.2.3" | awk '{print $1}')

3. Implement Health Checks and Monitoring

Robust health checks enable automated rollback decisions:

# In your Kubernetes deployment
spec:
  template:
    spec:
      containers:
      - name: myapp
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

4. Staging Rollback Testing

Always test rollback procedures in staging:

#!/bin/bash
# Staging rollback test script
STAGING_APP="myapp-staging"

echo "Testing rollback in staging..."
CURRENT_REV=$(argocd app get $STAGING_APP -o json | jq -r '.status.sync.revision')
echo "Current revision: $CURRENT_REV"

# Perform test rollback
argocd app rollback $STAGING_APP 5
argocd app wait $STAGING_APP --health

# Validate functionality
./run-integration-tests.sh

# Roll forward again
argocd app sync $STAGING_APP
echo "Staging rollback test completed successfully"

5. Monitoring During Rollbacks

Implement comprehensive monitoring:

# Prometheus AlertManager rule example
groups:
- name: argocd-rollback
  rules:
  - alert: RollbackInProgress
    expr: argocd_app_info{sync_status!="Synced"}
    for: 30s
    labels:
      severity: warning
    annotations:
      summary: "ArgoCD rollback in progress for {{ $labels.name }}"
      
  - alert: RollbackFailed
    expr: argocd_app_info{sync_status="Unknown"} > 0
    for: 60s
    labels:
      severity: critical
    annotations:
      summary: "ArgoCD rollback failed for {{ $labels.name }}"

6. Automated Rollback with Circuit Breakers

For advanced teams, implement automated rollback triggers:

# Python example using ArgoCD API
import requests
import time
from prometheus_api_client import PrometheusConnect

def check_application_health(app_name, prometheus_url):
    prom = PrometheusConnect(url=prometheus_url)
    query = f'up{{job="{app_name}"}} == 0'
    result = prom.custom_query(query=query)
    return len(result) == 0  # Healthy if no down instances

def automated_rollback(app_name, argocd_server, token):
    if not check_application_health(app_name, prometheus_url):
        print(f"Health check failed for {app_name}, initiating rollback...")
        
        # Get previous revision
        history_url = f"{argocd_server}/api/v1/applications/{app_name}/revisions"
        headers = {"Authorization": f"Bearer {token}"}
        response = requests.get(history_url, headers=headers)
        revisions = response.json()
        
        if len(revisions) > 1:
            target_revision = revisions[1]["revision"]
            rollback_url = f"{argocd_server}/api/v1/applications/{app_name}/rollback"
            rollback_data = {"revision": target_revision}
            
            rollback_response = requests.post(rollback_url, json=rollback_data, headers=headers)
            
            if rollback_response.status_code == 200:
                print(f"Rollback initiated successfully for {app_name}")
                return True
            else:
                print(f"Rollback failed: {rollback_response.text}")
                return False

Comparisons and Alternatives

ArgoCD vs Argo Rollouts: When to Use What

ArgoCD Rollback is ideal for:

• Configuration changes
• Complete application version changes
• Multi-service rollbacks
• Git-driven rollback workflows

Argo Rollouts excels at:

• Fast application-only rollbacks
• Blue-green and canary deployments
• Traffic-based rollback decisions
• Progressive delivery scenarios

FluxCD Rollback Comparison

FluxCD handles rollbacks differently:

# FluxCD approach - suspend reconciliation, then fix Git
flux suspend kustomization myapp
git revert <bad-commit>
git push
flux resume kustomization myapp

The key difference: FluxCD requires Git-first rollbacks, while ArgoCD offers both cluster-first and Git-first options.

Helm-Based Rollbacks

If your ArgoCD application uses Helm charts:

# You can leverage Helm's native rollback capabilities
helm rollback myapp 3 -n myapp-namespace

# But this creates drift that ArgoCD will correct
# Better to use ArgoCD's rollback to maintain GitOps consistency

Real-World Case Study: The Midnight Database Migration Rollback

Let’s walk through a realistic scenario that many teams face:

The Situation

• Time: 2:15 AM EST
• Issue: Database migration in production API caused data corruption
• Impact: 500 errors on 30% of user requests
• Constraint: Must rollback within 5 minutes to meet SLA

The Response

Step 1: Immediate Assessment (30 seconds)

# Check current application status
argocd app get prod-api
# Status: Healthy (misleading - app is running but data is corrupt)

# Check recent deployments
argocd app history prod-api | head -5
# ID    DATE                           REVISION
# 23    2024-01-15 06:10:15 +0000 UTC  a1b2c3d (HEAD -> main) DB migration v2.1
# 22    2024-01-15 05:45:30 +0000 UTC  e4f5g6h Stable - pre-migration

Step 2: Disable Auto-Sync (15 seconds)

argocd app set prod-api --sync-policy none

Step 3: Execute Rollback (30 seconds)

# Roll back to revision 22 (pre-migration)
argocd app rollback prod-api 22 --timeout 300s

Step 4: Monitor Recovery (3 minutes)

# Watch sync progress
argocd app wait prod-api --health --timeout 300

# Verify application metrics
curl https://prod-api.example.com/health
# {"status": "healthy", "database": "connected", "version": "v2.0.8"}

Step 5: Incident Response (ongoing)

# Database rollback (parallel to application rollback)
kubectl exec -it prod-db-0 -- pg_dump --clean prod_db > backup_pre_migration.sql

# Coordinate with database team for data recovery
# Update incident status: Application rolled back successfully

The Outcome

• Total downtime: 4 minutes 23 seconds
• SLA impact: Within acceptable threshold
• Data loss: Minimal (transactions during migration window)
• Lessons learned: Always test database migrations in staging with production-like data volume

Post-Incident Actions

Git Repository Cleanup:

# Revert the problematic migration
git revert a1b2c3d
git commit -m "Revert database migration v2.1 - data corruption in prod"
git push origin main

# Re-enable auto-sync
argocd app set prod-api --sync-policy automated

Process Improvements:

• Implemented pre-migration database backups
• Added data integrity health checks
• Created automated rollback triggers for database corruption scenarios

Troubleshooting Common Rollback Failures

Issue: “Rollback operation timed out”

Symptoms:

Error: operation timed out after 300s

Solutions:

# Increase timeout
argocd app rollback myapp 5 --timeout 900s

# Check for resource-intensive startup procedures
kubectl describe pods -n myapp-namespace

# Consider rolling back in phases for complex applications

Issue: “Cannot rollback: revision not found”

Symptoms:

Error: revision 8 not found in application history

Solutions:

# Check available revisions
argocd app history myapp

# If history was pruned, find the Git commit directly
git log --oneline | head -10

# Use Git SHA instead of revision number
argocd app rollback myapp abc123def

Issue: “Auto-sync immediately overwrites rollback”

Symptoms: Application reverts to HEAD state within seconds of rollback.

Solutions:

# Disable auto-sync first
argocd app set myapp --sync-policy none

# Perform rollback
argocd app rollback myapp 6

# Fix in Git, then re-enable auto-sync
argocd app set myapp --sync-policy automated

Issue: “Partial rollback – some resources failed”

Symptoms: Some pods updated, others stuck in previous state.

Solutions:

# Force a complete sync
argocd app sync myapp --force --replace

# Check resource conflicts
kubectl get events -n myapp-namespace --sort-by='.lastTimestamp'

# Manual intervention for stuck resources
kubectl delete pod <stuck-pod> -n myapp-namespace

Quick Reference: ArgoCD Rollback Cheat Sheet

Essential Commands

# View application history
argocd app history <app-name>

# Basic rollback
argocd app rollback <app-name> <revision>

# Rollback with pruning
argocd app rollback <app-name> <revision> --prune

# Disable/enable auto-sync
argocd app set <app-name> --sync-policy none
argocd app set <app-name> --sync-policy automated

# Monitor rollback progress
argocd app wait <app-name> --health --timeout 600s

# Check application status
argocd app get <app-name>

Emergency Rollback Procedure

1. Assess the situation: Check application health and recent deployments
2. Disable auto-sync: argocd app set <app> --sync-policy none
3. Identify target revision: argocd app history <app>
4. Execute rollback: argocd app rollback <app> <revision>
5. Monitor progress: argocd app wait <app> --health
6. Verify recovery: Check application metrics and health endpoints
7. Fix in Git: Revert or patch the problematic changes
8. Re-enable auto-sync: argocd app set <app> --sync-policy automated

Pre-Rollback Checklist

• [ ] Identify the last known good revision
• [ ] Check if auto-sync is enabled
• [ ] Verify rollback won’t affect persistent data
• [ ] Ensure monitoring is active
• [ ] Coordinate with dependent services
• [ ] Have Git access ready for permanent fixes

Quick Code Snippets

Essential Rollback Commands

# View application history
argocd app history myapp

# Simple rollback to revision 5
argocd app rollback myapp 5

# Rollback with resource pruning
argocd app rollback myapp 3 --prune

# Rollback with extended timeout
argocd app rollback myapp 2 --timeout 600s

Auto-Sync Management

# Disable auto-sync before rollback
argocd app set myapp --sync-policy none

# Perform rollback
argocd app rollback myapp 4

# Re-enable auto-sync after Git fix
argocd app set myapp --sync-policy automated

Rollback Monitoring

# Wait for rollback completion
argocd app wait myapp --health --timeout 300

# Check application status
argocd app get myapp

# Monitor specific resources
kubectl get pods -n myapp-namespace -w

Emergency Rollback Script

#!/bin/bash
APP_NAME="$1"
TARGET_REV="$2"

# Quick rollback with safety checks
argocd app set $APP_NAME --sync-policy none
argocd app rollback $APP_NAME $TARGET_REV --timeout 300s
argocd app wait $APP_NAME --health --timeout 300

if [ $? -eq 0 ]; then
    echo "✅ Rollback successful"
else
    echo "❌ Rollback failed"
    exit 1
fi

Git Revert for GitOps Compliance

# Revert problematic commit
git revert <commit-sha>
git push origin main

# ArgoCD will auto-sync to reverted state
# No manual rollback needed

Health Check Integration

# Rollback with health validation
argocd app rollback myapp 3
sleep 30
if curl -f https://myapp.example.com/health; then
    echo "App healthy after rollback"
else
    echo "App unhealthy - investigate"
fi

Bulk Application Rollback

#!/bin/bash
APPS=("app1" "app2" "app3")
TARGET_REV="5"

for app in "${APPS[@]}"; do
    echo "Rolling back $app to revision $TARGET_REV"
    argocd app set $app --sync-policy none
    argocd app rollback $app $TARGET_REV
    argocd app wait $app --health --timeout 300
done

ApplicationSet Revision Update

# Update ApplicationSet to rollback all generated apps
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: microservices
spec:
  generators:
  - list:
      elements:
      - name: service-a
        revision: "abc123"  # Previous stable commit
      - name: service-b
        revision: "def456"  # Previous stable commit

Conclusion: Building Rollback Resilience

Mastering ArgoCD rollbacks isn’t just about memorizing commands—it’s about building a comprehensive strategy that balances immediate incident response with long-term GitOps principles. The techniques covered in this guide provide you with multiple tools for different scenarios:

• UI rollbacks for visual confirmation and team collaboration
• CLI rollbacks for automation and scripting
• Auto-sync strategies for maintaining GitOps integrity
• Complex scenario handling for ApplicationSets and multi-source applications

Remember that the best rollback is the one you never need to perform. Invest in robust testing, staging environments, and gradual deployment strategies. But when rollbacks become necessary, having these skills and procedures in place can mean the difference between a minor blip and a major outage.

The DevOps landscape continues to evolve, and GitOps tools like ArgoCD are constantly improving their rollback capabilities. Stay current with the latest releases, participate in the community, and regularly review and test your rollback procedures.

Your future self—and your on-call teammates—will thank you for the preparation.

Additional Resources

Official Documentation

• ArgoCD Rollback Documentation
• ArgoCD Sync Policies
• ApplicationSet Documentation

Community Resources

• ArgoCD GitHub Issues
• CNCF ArgoCD Slack Channel
• GitOps Working Group

Related Tools

• Argo Rollouts
• Flux
• Jenkins X

Have questions about ArgoCD rollbacks or want to share your own experiences? Connect with the community on our DevOps Slack workspace or follow @thedevopstooling for the latest GitOps insights.