Eventline is now open source and available on GitHub !

If you are still using the old Eventline platform, contact us to migrate to the new service, and head to the new documentation website for more information.

Triggers

Introduction

Triggers are used to react to events: when the events described in the trigger occurs, Eventline will instantiate one or more pipelines.

Data schema

Trigger data contain the following fields:

connector (string)
The name of the connector associated with the trigger.
event (string)
The name of the event the trigger reacts to.
parameters (object)
Subscription parameters for the connector and event (optional).
filters (array)
A list of filters which must match the event for the trigger to activate (optional).
identity (string)
The name of the identity used to authenticate against the external service (optional).
pipelines (array)
A list of pipelines to instantiate when the trigger is activated.

Example

type: "trigger"
version: 1
name: "github-push"
data:
  connector: "github"
  event: "push"
  parameters:
    organization: "example"
  filters:
    - path: "/branch"
      is_equal_to: "main"
  identity: "github-token"
  pipelines:
    - "process-github-push"

In this example, the trigger will be activated when a github.push event is received, indicating that there has been a set of commit pushed to the main branch of any repository in the example organization. The github-token identity will be used to register the trigger on GitHub. On activation, the process-github-push pipeline will be instantiated.

Subscription

Each trigger is configured to monitor specific events. These events are defined by three values: the connector, the event name and the set of parameters.

Connectors designate either entire platforms (e.g. github) or abstract domains (e.g. time), and are used to group events.

Events themselves have a name. For example, the event emitted when a repository is created on GitHub is named repository_creation.

Finally, parameters provide more information about what we actually want to react to. Each event has its own set of parameters. For the repository_creation event, the parameters contains the name of the GitHub organization.

See the connector pages for the lists of supported events.

Filters

Filters are used to restrict the set of events which will activate the trigger. While parameters are used to select large categories of events, filters allow to select events by matching their content.

Each filter is an object made of a path, and zero or more predicates. The path is a JSON pointer applied to the data of the event.

Warning
If the path of a filter does not resolve to a value in the data field of the event, the filter will not match the event. As a result, a filter without any predicate will always match as long as the path if found in the data field.

Predicates are additional members which are applied to the value referenced by the path. An event matches a filter if all predicates are true.

The following predicates are supported:

is_equal_to
Matches if the value referenced by the path is equal to the value associated with the predicate.
matches
The associated value is a regular expression; the predicate matches if the value referenced by the path is a string which matches this regular expression. Eventline supports the PCRE syntax (version 8.40).

Example

type: "trigger"
version: 1
name: "github-ruby-push"
data:
  connector: "github"
  event: "push"
  parameters:
    organization: "example"
  filters:
    - path: "/repository"
      matches: "^ruby-"
    - path: "/branch"
      is_equal_to: "main"
  identity: "github-token"
  pipelines:
    - "github-ruby-push"

This trigger will be activated each time a set of commits is pushed on the main branch of a repository whose name starts with the ruby- prefix.

Identity

Most connectors handle events triggered on an external platform. To access these events, Eventline must usually authenticate against this platform, hence the need for an identity.

As we have seen before, connectors are used to group events; they are also used to group identities. For example, the github connector supports two types of identities: oauth2 and token.

Some connectors do not require any authentication, for example the time connector. Triggers associated with these connectors do not need to include an identity data field.