Trigger Argo Workflows from Events with Argo Events (2026)

Argo Events can trigger Argo Workflows, but it’s not just a simple webhook; it’s a declarative event-driven orchestration system that decouples event sources from workflow execution.

Let’s see it in action. Imagine you have a Git repository. When a new commit is pushed, you want to trigger a specific Argo Workflow to build and deploy your application.

Here’s a simplified view of the components:

1. Event Source (e.g., GitHub): This is where the event originates. In our case, a push event on a GitHub repository.
2. Argo Events Sensor: This component listens for events from the event source. It’s configured to filter and process incoming events.
3. Argo Events Trigger: When the Sensor detects a relevant event, it invokes a Trigger. The Trigger specifies what action to take.
4. Argo Workflow: This is the target of the Trigger. The Trigger can create a Workflow resource in Kubernetes, which then executes your defined workflow.

Let’s walk through a concrete example.

Scenario: Trigger a Workflow on GitHub Push

First, you need an Argo Events EventListener and a Sensor.

EventListener: This CRD defines how Argo Events will receive events. It exposes an HTTP endpoint that event sources can send data to.

apiVersion: argoproj.io/v1alpha1
kind: EventListener
metadata:
  name: github-listener
spec:
  triggers:
    - name: github-push-trigger
      # This is the webhook URL Argo Events exposes. You'll configure GitHub to send events here.
      ref: github-sensor # Points to the Sensor that will process this event

Sensor: This CRD defines the logic for processing events. It specifies the event source and what action to take when an event matches.

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: github-sensor
spec:
  template:
    serviceAccountName: argo-events-sa # Ensure this SA has permissions to create Workflows
  dependencies:
    - name: github-event
      eventSourceName: github # Name of the EventSource CRD
      eventSourceType: github # Type of the EventSource
      filters:
        # Filter for push events
        - path: "body.ref"
          type: "string"
          value: "refs/heads/main" # Trigger only on pushes to the main branch
  # This trigger defines what happens when the dependency (github-event) is met.
  triggers:
    - name: trigger-workflow
      resource:
        # This tells Argo Events to create a Workflow.
        kind: Workflow
        create:
          function: "argo-workflows.argoproj.io/v1alpha1.Workflow"
          # This is the name of the Workflow to be created.

          # You can use templating here to dynamically name it, e.g., "my-workflow-{{.github.ref}}"

          name: "my-github-triggered-workflow"
      # This maps data from the event to parameters in the Workflow.
      parameters:
        - src:
            dependencyName: github-event
            dataKey: "body.commits.0.id" # Get the commit ID from the GitHub event payload
          dest: "parameters.commit-sha" # This parameter will be available in the Workflow
        - src:
            dependencyName: github-event
            dataKey: "body.repository.clone_url"
          dest: "parameters.repo-url"

EventSource: This CRD configures how Argo Events connects to the event provider. For GitHub, you’d typically use a webhook.

apiVersion: argoproj.io/v1alpha1
kind: EventSource
metadata:
  name: github
spec:
  github:
    # This is the webhook secret you'll configure in GitHub.
    # It's used for signature verification.
    webhook:
      secretToken:
        name: github-webhook-secret # Kubernetes Secret containing the webhook secret
        key: secret
      # This is the endpoint Argo Events exposes for GitHub webhooks.
      # You'll get this URL from your LoadBalancer or Ingress.
      endpoint: "/github/webhook"

Kubernetes Secrets: You’ll need a Kubernetes Secret for your GitHub webhook secret.

apiVersion: v1
kind: Secret
metadata:
  name: github-webhook-secret
type: Opaque
stringData:
  secret: "your-super-secret-github-webhook-secret"

Argo Workflow Definition: Your Argo Workflow will need to accept the parameters passed by the Sensor.

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: build-deploy- # Prefix for generated workflow names
spec:
  entrypoint: build-and-deploy
  arguments:
    parameters:
      - name: commit-sha
        value: "" # Default value, will be populated by Sensor
      - name: repo-url
        value: ""
  templates:
    - name: build-and-deploy
      inputs:
        parameters:
          - name: commit-sha
          - name: repo-url
      script:
        image: alpine:latest
        command: [sh, -c]
        source: |

          echo "Building from commit: {{inputs.parameters.commit-sha}}"


          echo "Cloning repository: {{inputs.parameters.repo-url}}"

          # Your build and deploy logic here

          git clone {{inputs.parameters.repo-url}}


          cd $(basename {{inputs.parameters.repo-url}} .git)


          git checkout {{inputs.parameters.commit-sha}}

          echo "Build and deploy complete."

How it all connects:

1. GitHub Configuration: You create a webhook in your GitHub repository settings. The payload URL will be the public endpoint of your Argo Events EventListener (e.g., http://your-argo-events-service.your-domain.com/github/webhook). You’ll also configure the webhook secret.
2. Event Arrival: When a push event occurs on your GitHub repo (specifically to the main branch, as per the filter), GitHub sends an HTTP POST request to the EventListener’s endpoint with the event payload.
3. EventListener & Sensor Activation: The EventListener receives the request and, based on its configuration, passes it to the github-sensor. The Sensor’s github-event dependency checks the incoming payload.
4. Dependency Matching: The Sensor filters the event: it checks if body.ref equals refs/heads/main. If it matches, the dependency is satisfied.
5. Trigger Execution: The trigger-workflow in the Sensor is then executed. It reads body.commits.0.id and body.repository.clone_url from the event payload and maps them to the commit-sha and repo-url parameters.
6. Workflow Creation: The Sensor instructs Argo Events to create a new Workflow resource in your Kubernetes cluster. It uses the my-github-triggered-workflow template (or a dynamically generated name if you’ve templated it) and passes the extracted commit-sha and repo-url as arguments to the Workflow.
7. Workflow Execution: Argo Workflows picks up the newly created Workflow resource and begins its execution, using the provided commit SHA and repository URL to perform the build and deploy.

The most surprising thing about this setup is that Argo Events doesn’t directly execute your workflow logic; it acts as an intelligent dispatcher, translating external events into native Kubernetes resource creations, primarily Argo Workflows. This allows your workflows to be triggered by a vast array of event sources without modifying your workflow definitions themselves.

The create block within the Trigger is powerful. You can create not just Workflows, but also other Kubernetes resources. This opens up possibilities for using events to manage any part of your Kubernetes infrastructure declaratively.

The next step is often handling more complex event scenarios, like coordinating multiple events before triggering a workflow, or implementing retry logic when a trigger fails.