> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/using-pipekit/argo-events.md).

# Argo Events

[Argo Events](https://argoproj.github.io/argo-events/) is an event-driven automation framework for Kubernetes. It listens to sources such as webhooks, message queues, cloud events, and calendars, and fires a trigger when an event arrives. Pipekit exposes an Argo Events custom trigger, so any of those sources can launch a Pipekit run.

When a Sensor fires, it submits an inline Argo Workflow to Pipekit as a governed [Run](/using-pipekit/runs.md). The run is routed to the [Cluster](/using-pipekit/clusters.md) you name, respects your organization's permissions, and appears in the [Runs dashboard](/using-pipekit/runs.md) with the `Argo Events` source label. This lets you keep your existing event-driven pipelines while gaining Pipekit's observability and access control over what they launch.

## How it works

The trigger is a gRPC `custom` trigger on your Argo Events Sensor. The Sensor dials the Pipekit control plane at `api.pipekit.io:443` over TLS and authenticates with your cluster API key. Pipekit reads the inline workflow from the trigger spec, resolves the target cluster by name within your organization, and submits the run.

## Prerequisites

You need an Argo Events installation in the cluster that runs your Sensor. Install it with Pipekit's build of Argo Events rather than the upstream images.

{% hint style="warning" %}
The Pipekit custom trigger uses `authToken` and `authHeader` fields that are not in upstream Argo Events. Both the `controller-manager` Deployment and the Sensor pods must run the Pipekit image `pipekit13/argo-events`. Stock Argo Events images will not attach the API key, and the trigger will fail to authenticate.
{% endhint %}

You also need a registered Pipekit cluster and its API key. The API key is shown when you [add a cluster](/using-pipekit/clusters.md) and can be [regenerated](/using-pipekit/clusters.md#generating-a-new-api-key) from the cluster's `Settings` tab. Note the cluster's name as well, which you set when creating it.

## Configure

### Store the cluster API key as a Secret

Create a Kubernetes Secret in the Sensor's namespace holding your cluster API key.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: pipekit-cluster-apikey
  namespace: argo-events
type: Opaque
stringData:
  apiKey: "<your-cluster-api-key>"
```

### Add the custom trigger to your Sensor

Add a `custom` trigger to your [Sensor](https://argoproj.github.io/argo-events/concepts/sensor/) that points at the Pipekit control plane.

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: pipekit-run
  namespace: argo-events
spec:
  dependencies:
    - name: webhook-dep
      eventSourceName: webhook
      eventName: pipekit
  triggers:
    - template:
        name: pipekit-submit
        custom:
          serverURL: api.pipekit.io:443
          secure: true
          authHeader: X-PIPEKIT-API-KEY
          authToken:
            name: pipekit-cluster-apikey
            key: apiKey
          spec:
            cluster: "my-cluster"
            workflow: |
              apiVersion: argoproj.io/v1alpha1
              kind: Workflow
              metadata:
                generateName: argo-events-
                namespace: argo
              spec:
                entrypoint: main
                arguments:
                  parameters:
                    - name: message
                      value: "default message"
                templates:
                  - name: main
                    inputs:
                      parameters:
                        - name: message
                    container:
                      image: alpine:3.20
                      command: [sh, -c]
                      args: ["echo {{inputs.parameters.message}}"]
          parameters:
            - src:
                dependencyName: webhook-dep
                dataKey: body.message
              dest: spec.arguments.parameters.0.value
```

### Trigger fields

| Field           | Required | Description                                                                           |
| --------------- | -------- | ------------------------------------------------------------------------------------- |
| `serverURL`     | Yes      | The Pipekit control plane gRPC endpoint. Use `api.pipekit.io:443`.                    |
| `secure`        | Yes      | Set to `true`. The connection uses TLS.                                               |
| `authHeader`    | Yes      | Set to `X-PIPEKIT-API-KEY`. This is the header Pipekit reads the API key from.        |
| `authToken`     | Yes      | A reference to the Secret key holding your cluster API key.                           |
| `spec.cluster`  | Yes      | The name of the Pipekit cluster to run on. Must match a cluster in your organization. |
| `spec.workflow` | Yes      | The inline Argo Workflow to submit, as a YAML string.                                 |
| `parameters`    | No       | Standard Argo Events parameter injection into the resolved workflow.                  |

`api.pipekit.io` serves a publicly trusted certificate, so no `certSecret` is needed.

### Inject event data

Use the trigger's `parameters` block to inject values from the event into the submitted workflow, the same way any Argo Events trigger does. The `src` selects a value from the event payload, and `dest` is a path into the trigger spec. In the example above, the webhook body's `message` field replaces the workflow's `message` parameter.

## Verify

Fire an event at your source, then open the [Runs dashboard](/using-pipekit/runs.md). Filter the source to `Argo Events` to find the run. The run behaves like any other Pipekit run once submitted.