How to Drive GitOps With Webhooks

Webhook-driven GitOps keeps Git as the source of truth: a build dispatches an event that bumps a manifest, and the reconciler syncs it.

On a successful build, POST a repository_dispatch to the environment repo. A workflow there updates the image tag in a manifest and commits, and the GitOps controller reconciles the cluster.

Steps

• Build and push the image with an immutable tag.
• Dispatch an event to the environment repo with the new tag.
• A workflow updates the manifest and commits; the controller reconciles.

Bump workflow

on:
  repository_dispatch:
    types: [image-pushed]
jobs:
  bump:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          yq -i '.image.tag = "${{ github.event.client_payload.tag }}"' deploy/values.yaml
          git config user.name ci-bot
          git commit -am "bump image to ${{ github.event.client_payload.tag }}"
          git push

Gotchas

• Use immutable tags (a digest or build id), not latest, so the reconciler detects the change.
• Scope the dispatch token to the environment repo only.

Related guides