A successful build doesn't mean your new version is live.
Suppose Git requests v2, while the live Kubernetes Deployment still references v1. The new image might already be in the registry, but the cluster configuration has not caught up.
This is a useful way to understand Argo CD: follow one configuration change from Git to the cluster, then check what that change actually achieved.
The example below is illustrative. The image names are placeholders, and the diff is not a complete Kubernetes manifest.
Separate the responsibilities
For this container-based example, the delivery workflow has three distinct parts:
| Responsibility | What happens |
|---|---|
| CI | Test the application, build a container image and publish it to a registry. |
| Git | Store the deployment configuration that references the intended image version. |
| Argo CD | Compare desired configuration with live resources and synchronize changes. |
Kubernetes controllers then carry out the rollout after the resource configuration changes. Argo CD does not build the container image.
The official CI integration guide describes this separation between publishing an image, updating manifests in Git and synchronizing the application.
Make the difference visible
Imagine the image-reference change looks like this:
- image: registry.example.com/demo-app:v1 + image: registry.example.com/demo-app:v2 The first line represents the live configuration. The second represents the desired configuration in Git.
Argo CD compares the application resources against the desired state from its configured source. If the tracked configuration differs, the application can be reported as OutOfSync.
That is a comparison result. It does not, by itself, tell you whether the difference is an intended release, an unexpected manual edit or an application-health problem. The core concepts distinguish target state, live state, sync status and health.
Review, then synchronize
For this walkthrough, use a manual sync so the change can be inspected before it is applied.
Review the target application, destination, revision and resource diff. Check that the image reference and any accompanying changes are the ones you intend to release.
For an existing Argo CD Application named demo-app, with the CLI authenticated to the intended Argo CD instance, the basic commands are:
# Inspect the application and its status argocd app get demo-app # Review the difference argocd app diff demo-app # Apply the desired configuration when ready argocd app sync demo-app Replace demo-app with your actual Application name. The diff command returns exit code 1 when it finds differences, so account for that if you use it in scripts.
References: app get, app diff and app sync.
Synced answers one question
After synchronization, the live image reference can match the desired reference in Git.
Synced means Argo CD sees no differences in the configuration it tracks. It does not prove that the application is ready to serve users.
Resource health is a separate assessment. For example, a Deployment's updated resource configuration and the readiness of its rollout are different things. See the resource-health documentation.
Before calling a release complete, I check both configuration and application behaviour:
- Is the expected revision and image reference applied?
- Are the relevant resources healthy and the rollout ready?
- Does the user-facing path work, including the dependencies it needs?
- Do logs and monitoring show errors after the change?
The exact checks depend on the application. A green sync status only answers the configuration part.
Where automated sync fits
Manual sync is a policy choice for this example. Argo CD can also synchronize automatically when configured to do so.
Automatic self-healing is a separate setting for responding to live-state deviations. Avoid assuming that every direct cluster edit will automatically be reverted. The behaviour depends on the configured policy; the automated sync guide covers those options.
Automation changes when synchronization starts. It does not remove the need to verify the rollout and application behaviour.
The takeaway
Keep the sequence easy to explain: build the image, declare the desired configuration, review the difference, synchronize and verify.
What do you check before calling a deployment complete?
I'm Ameni Ben Saada, a software engineer working across full-stack development and cloud delivery. More about my work: amenibensaada.tn.
