Skip to content
Documentation Background

CI integration and webhooks

A CI pipeline and Argo CD solve different halves of delivery. CI turns a commit into a tested artifact and ends. Argo CD runs forever and keeps the cluster equal to what Git says. Wiring them together is mostly about two questions: how fast does Argo CD learn that Git changed, and how does a pipeline stay in control of what reaches the cluster.


CIArgo CD
RunsTriggered by a push, a pull request, or a schedule, and finishesContinuously, independent of CI
ModelImperative, sequential stepsDeclarative reconciliation of live state to Git
Typical workCompile, unit test, build and scan an image, lint manifestsRender manifests, compare, apply, report health
Failure meansThe build is redThe cluster differs from Git, or a sync failed

A pipeline cannot wait on Argo CD the way it waits on a build step, because Argo CD does not run on the pipeline’s schedule. The link between them is Git. CI writes a change into the configuration repository, and Argo CD picks it up.

flowchart LR
    A["Source repository"] --> B["CI: build, test, scan"]
    B --> C["Registry: image"]
    B --> D["Config repository: commit new image tag"]
    D --> E["Argo CD: detect and sync"]
    E --> F["Cluster"]

Keeping application source and deployment configuration in separate repositories makes the config repository an audit log of what was deployed and when, and stops config commits from retriggering CI builds. The tradeoffs are covered in repository strategies. Continuous integration covers the CI side, and the GitHub Actions and Jenkins sections cover specific tools.


The application controller and the repo server check each repository on a timer. timeout.reconciliation in argocd-cm sets the interval, 120 seconds by default, and timeout.reconciliation.jitter (60 seconds by default) adds a random delay of up to that much per Application so that thousands of refreshes do not land together. A change therefore takes between two and three minutes to be noticed.

apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
data:
timeout.reconciliation: 120s
timeout.reconciliation.jitter: 60s

Changing timeout.reconciliation requires restarting the application controller and the repo server:

Terminal window
kubectl rollout restart statefulset -n argocd -l app.kubernetes.io/component=application-controller
kubectl rollout restart deployment -n argocd -l app.kubernetes.io/component=repo-server

A shorter interval finds changes sooner, and costs more CPU in the controller, more repo server work, and more requests to the Git host, which may rate-limit you. Setting it to 0 disables polling and then makes webhooks or manual refreshes the only triggers, which is rarely what you want.

A refresh re-reads the source, using the manifest cache when the revision is unchanged. A hard refresh bypasses the cache and re-renders, which matters after changing a plugin or a chart in place:

Terminal window
argocd app get shop-api --refresh
argocd app get shop-api --hard-refresh

A webhook removes the polling delay. The Git host calls Argo CD when a push happens, and Argo CD refreshes the Applications that use that repository. Keep polling as a safety net, since webhook deliveries can fail. The default interval plus webhooks is the recommended setup.

The endpoint is /api/webhook on the Argo CD server, for example https://argocd.example.com/api/webhook. Argo CD understands events from GitHub, GitLab, Bitbucket Cloud, Bitbucket Server, Azure DevOps, and Gogs.

  1. Create the webhook in the Git host with the payload URL above. On GitHub, set the content type to application/json, since the form-encoded default is not supported. Choose a shared secret.
  2. Store the secret in argocd-secret under the key for the provider:
ProviderKey in argocd-secret
GitHubwebhook.github.secret
GitLabwebhook.gitlab.secret
Bitbucket Cloudwebhook.bitbucket.uuid
Bitbucket Serverwebhook.bitbucketserver.secret
Gogswebhook.gogs.secret
Azure DevOpswebhook.azuredevops.username and webhook.azuredevops.password
Terminal window
kubectl patch secret argocd-secret -n argocd --type merge \
-p '{"stringData": {"webhook.github.secret": "<shared-secret>"}}'

With the Helm chart, set configs.secret.githubSecret (and the sibling keys) instead.

The secret is optional because a webhook payload is untrusted input that can only trigger a refresh, which the poll would do anyway. On an Argo CD instance reachable from the internet, set the secret and limit the payload size with webhook.maxPayloadSizeMB (50 by default) in argocd-cm, because the endpoint has no rate limiting. After a bulk merge to a monorepo, webhook.refresh.jitter and webhook.refresh.jitter.threshold spread the resulting refreshes out.

A push to branch x also refreshes Applications tracking a tag named x, since the handler does not distinguish the two.

Argo CD also accepts events from OCI registries, so pushing a new chart version to GitHub Container Registry refreshes Applications whose repoURL is that registry and whose targetRevision (an exact tag or a semver constraint) matches. Only published events for the container package type are used. ApplicationSet Git generators have their own webhook configuration.

In a repository that holds many Applications, every commit changes the revision that keys the manifest cache, so one change would re-render every Application. The annotation argocd.argoproj.io/manifest-generate-paths lists the repository paths an Application’s manifests depend on. If a commit changes none of them, Argo CD reuses the cache and skips the refresh. Without webhooks it compares commits in Git history, and with webhooks it uses the changed-file list in the payload (GitHub, GitLab, and Gogs).

metadata:
annotations:
argocd.argoproj.io/manifest-generate-paths: .;../shared # this app's path, plus a shared directory

A leading / makes a path absolute within the repository, and a relative path starts from the Application’s path. Separate several paths with semicolons.


A webhook alone deploys whatever lands on the branch, which skips everything CI does. With automated sync, a bad manifest merged to the tracked branch is applied within minutes. Three arrangements keep CI in control.

Validate before merge. Run checks on pull requests to the config repository, so only validated manifests reach the tracked branch:

Terminal window
kustomize build overlays/prod > rendered.yaml
yamllint rendered.yaml
kubeconform -strict -summary rendered.yaml

Argo CD’s own checks help too. argocd app diff shows what a change would do, and argocd app manifests prints the rendered result.

Promote through the repository. The pipeline that builds an image commits the new tag to the config repository, on a branch per environment or in a directory per environment. Promotion from dev to prod is then a commit or pull request, reviewed and recorded.

Sync the exact revision. With manual sync, the pipeline triggers the deployment itself, after its checks pass, for the commit that passed them. This avoids deploying a newer commit that nobody tested:

Terminal window
# authenticate with a project role token, scoped to sync one project
export ARGOCD_SERVER=argocd.example.com
export ARGOCD_AUTH_TOKEN="$ARGOCD_TOKEN"
argocd app sync shop-api --revision "$GIT_COMMIT_SHA" --grpc-web
argocd app wait shop-api --health --sync --timeout 300 --grpc-web

argocd app wait makes the pipeline fail when the application does not become healthy, which gives CI a result for the deployment. The token should come from a project role allowing only sync and get on that project, and be stored as a CI secret.

ApproachWho triggers deploymentStrengthWeakness
Commit to config repo, automated syncArgo CD, after a mergeFully pull-based, no Argo CD credentials in CICI cannot see the deployment result, so add notifications
Commit to config repo, manual sync from CIThe pipelineCI sees pass or fail for the exact revisionCI needs an Argo CD token
Pull request to config repoA reviewer mergingHuman approval, full audit trailSlower

Many teams combine the first approach for dev and the last for production, and use notifications to report back to the team.


SymptomLikely causeFix
A pushed change appears after two to three minutesNo webhook, so the poll found itConfigure the webhook, or accept the delay
The webhook delivery shows 400 or a signature errorContent type is not application/json, or the secret differsSet the content type and compare the secret in argocd-secret
The webhook arrives but no Application refreshesThe repository URL in the event differs from the Application’s repoURLMatch the URL form (HTTPS vs SSH, .git suffix) or check the event filter
A change to timeout.reconciliation has no effectThe controller and repo server were not restartedRestart both
A chart or plugin change is not picked upThe cached manifests are still validRun a hard refresh
Every commit refreshes every Application in a monorepoNo manifest-generate-paths annotationsAdd them, with the paths each Application depends on
The pipeline’s sync is rejectedThe token’s role lacks sync or override, or the Application uses automated syncFix the role policy, or use the commit-based handoff
Git host rate-limits Argo CDThe polling interval is too short for the number of repositoriesLengthen the interval and rely on webhooks