Argo CD can be triggered to sync Kubernetes manifests from a Git repository by a GitHub Actions workflow.
Here’s a basic GitHub Actions workflow that triggers an Argo CD sync. This example assumes you have an Argo CD instance running and accessible, and your GitHub repository contains the Kubernetes manifests Argo CD should deploy.
name: Trigger Argo CD Sync
on:
push:
branches:
- main # Trigger sync when main branch is updated
jobs:
trigger_argo_sync:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Trigger Argo CD Sync
env:
ARGOCD_URL: "https://argocd.example.com" # Replace with your Argo CD URL
ARGOCD_TOKEN: ${{ secrets.ARGOCD_TOKEN }} # Create a GitHub secret for your Argo CD token
APP_NAME: "my-app" # Replace with your Argo CD Application name
NAMESPACE: "argocd" # Replace with the namespace where your Argo CD Application resides
run: |
# Install Argo CD CLI if not already available
if ! command -v argocd &> /dev/null; then
curl -sSL -o argocd-v2.12.3.tar.gz https://github.com/argoproj/argo-cd/releases/download/v2.12.3/argocd-linux-amd64
chmod +x argocd-v2.12.3.tar.gz
sudo mv argocd-v2.12.3.tar.gz /usr/local/bin/argocd
fi
# Log in to Argo CD
argocd login $ARGOCD_URL --username admin --password $ARGOCD_TOKEN --insecure
# Trigger the sync
argocd app sync $APP_NAME --namespace $NAMESPACE --async
This workflow sets up a common pattern: when code is pushed to the main branch, it checks out the repository, logs into your Argo CD instance using a token stored as a GitHub secret, and then triggers a sync for a specific Argo CD Application. The --async flag means the workflow won’t wait for the sync to complete, which is usually desirable for CI/CD pipelines.
The core mechanism Argo CD uses to track changes is Git. When you create an Argo CD Application, you point it to a specific Git repository and a specific path within that repository containing your Kubernetes manifests. Argo CD continuously polls this repository (or receives webhook notifications if configured) to detect changes. When it detects a change that deviates from the desired state in Kubernetes, it flags the Application as "OutOfSync."
The argocd app sync command is the direct instruction to Argo CD to reconcile the state of the cluster with the state defined in the Git repository for a given Application. When you run this command, Argo CD fetches the latest manifests from the configured Git repository, compares them to the current state of resources in your Kubernetes cluster, and applies the necessary changes (create, update, delete) to make the cluster match the Git state. The --async flag is crucial here because it tells the Argo CD CLI to return immediately after initiating the sync, rather than blocking until the sync operation is fully completed. This allows your GitHub Actions workflow to finish quickly, and you can monitor the sync status directly within the Argo CD UI or via argocd app get <appName>.
The actual "trigger" is the argocd app sync command. This command instructs the Argo CD controller to re-evaluate the specified Application. The controller then compares the commit SHA currently deployed in the cluster for that Application against the latest commit SHA in the configured Git repository. If they differ, Argo CD proceeds to create or update Kubernetes resources according to the manifests found in the new commit. The argocd login command is essential to authenticate the CLI with your Argo CD instance, ensuring that the sync command is authorized to make changes. The ARGOCD_TOKEN is typically generated within Argo CD by creating a dedicated service account or using an existing user’s credentials, and then exporting a JWT token.
A common point of confusion is how Argo CD knows which commit to sync. By default, when you sync an Application, Argo CD will attempt to sync to the latest commit in the branch specified in the Application’s Git source configuration. If your Application is configured to sync from a specific branch (e.g., main), running argocd app sync my-app will pull down the manifests from the latest commit on main. You can also explicitly specify a commit SHA to sync to using argocd app sync my-app --revision <commit-sha>. This explicit revision sync is powerful for rollback scenarios or for deploying specific, known-good states.
The Argo CD CLI’s login command, when used with a token, doesn’t store credentials persistently by default. This means each time the GitHub Actions runner executes the workflow, it needs to re-authenticate. The --insecure flag is often used in CI/CD environments to bypass TLS certificate verification if your Argo CD instance uses a self-signed or untrusted certificate. For production, it’s highly recommended to configure proper TLS certificates and remove the --insecure flag, or use argocd login --grpc-web --plaintext if your Argo CD instance is configured for it. The token itself should be generated with minimal necessary permissions. In Argo CD, you can create a Secret of type argocd.argoproj.io/token or use a ServiceAccount and generate a token from it.
The next thing you’ll likely want to tackle is handling sync failures. If the argocd app sync command completes but the Application remains OutOfSync or enters a Degraded state, you’ll need a strategy to detect and potentially retry or alert.