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.
Two different kinds of process
Section titled “Two different kinds of process”| CI | Argo CD | |
|---|---|---|
| Runs | Triggered by a push, a pull request, or a schedule, and finishes | Continuously, independent of CI |
| Model | Imperative, sequential steps | Declarative reconciliation of live state to Git |
| Typical work | Compile, unit test, build and scan an image, lint manifests | Render manifests, compare, apply, report health |
| Failure means | The build is red | The 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.
How Argo CD notices a change
Section titled “How Argo CD notices a change”Polling
Section titled “Polling”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: v1kind: ConfigMapmetadata: name: argocd-cm namespace: argocddata: timeout.reconciliation: 120s timeout.reconciliation.jitter: 60sChanging timeout.reconciliation requires restarting the application controller and the repo server:
kubectl rollout restart statefulset -n argocd -l app.kubernetes.io/component=application-controllerkubectl rollout restart deployment -n argocd -l app.kubernetes.io/component=repo-serverA 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:
argocd app get shop-api --refreshargocd app get shop-api --hard-refreshWebhooks
Section titled “Webhooks”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.
- 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. - Store the secret in
argocd-secretunder the key for the provider:
| Provider | Key in argocd-secret |
|---|---|
| GitHub | webhook.github.secret |
| GitLab | webhook.gitlab.secret |
| Bitbucket Cloud | webhook.bitbucket.uuid |
| Bitbucket Server | webhook.bitbucketserver.secret |
| Gogs | webhook.gogs.secret |
| Azure DevOps | webhook.azuredevops.username and webhook.azuredevops.password |
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.
Monorepos
Section titled “Monorepos”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 directoryA leading / makes a path absolute within the repository, and a relative path starts from the Application’s path. Separate several paths with semicolons.
Letting CI gate the deployment
Section titled “Letting CI gate the deployment”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:
kustomize build overlays/prod > rendered.yamlyamllint rendered.yamlkubeconform -strict -summary rendered.yamlArgo 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:
# authenticate with a project role token, scoped to sync one projectexport ARGOCD_SERVER=argocd.example.comexport ARGOCD_AUTH_TOKEN="$ARGOCD_TOKEN"
argocd app sync shop-api --revision "$GIT_COMMIT_SHA" --grpc-webargocd app wait shop-api --health --sync --timeout 300 --grpc-webargocd 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.
Choosing a handoff
Section titled “Choosing a handoff”| Approach | Who triggers deployment | Strength | Weakness |
|---|---|---|---|
| Commit to config repo, automated sync | Argo CD, after a merge | Fully pull-based, no Argo CD credentials in CI | CI cannot see the deployment result, so add notifications |
| Commit to config repo, manual sync from CI | The pipeline | CI sees pass or fail for the exact revision | CI needs an Argo CD token |
| Pull request to config repo | A reviewer merging | Human approval, full audit trail | Slower |
Many teams combine the first approach for dev and the last for production, and use notifications to report back to the team.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| A pushed change appears after two to three minutes | No webhook, so the poll found it | Configure the webhook, or accept the delay |
| The webhook delivery shows 400 or a signature error | Content type is not application/json, or the secret differs | Set the content type and compare the secret in argocd-secret |
| The webhook arrives but no Application refreshes | The repository URL in the event differs from the Application’s repoURL | Match the URL form (HTTPS vs SSH, .git suffix) or check the event filter |
A change to timeout.reconciliation has no effect | The controller and repo server were not restarted | Restart both |
| A chart or plugin change is not picked up | The cached manifests are still valid | Run a hard refresh |
| Every commit refreshes every Application in a monorepo | No manifest-generate-paths annotations | Add them, with the paths each Application depends on |
| The pipeline’s sync is rejected | The token’s role lacks sync or override, or the Application uses automated sync | Fix the role policy, or use the commit-based handoff |
| Git host rate-limits Argo CD | The polling interval is too short for the number of repositories | Lengthen the interval and rely on webhooks |