Gateway¶

imbi-gateway receives webhooks from external systems, for example GitHub, PagerDuty, and SonarQube. For each delivery, it finds the Imbi projects that the delivery is about, records the delivery, and runs the rules of the webhook. A rule calls an action, for example "create a release" or "start an agent task".

The gateway runs on port 8003. The all-in-one image serves it under /gateway.

The webhook URL¶

Each Webhook has its own URL:

POST https://<imbi host>/gateway/notifications/<webhook id>

The Notification Path on the webhook detail page shows /<webhook id>. The endpoint has no bearer check. To prove that a delivery is genuine, use a signing secret (see Signature verification).

The body must be JSON.

Status codes¶

The gateway returns 204 when one of these is true:

• No webhook has this id.
• The webhook has no integration.
• The signature is missing or does not verify.
• The Identifier Selector does not resolve in the body.
• No project has that identifier for the integration.
• The webhook-actions capability of the integration is off. The gateway records the delivery, but runs no rule.
• No rule matches.

A scheduled task with a gateway target records 204 as no_effect. See Scheduled Tasks.

How the gateway processes a delivery¶

1. It reads the Webhook, its organization, its integration, and its rules.
2. For a GitHub integration, it verifies the signature when the webhook has a secret.
3. It reads the project identifier from the body with the Identifier Selector.
4. It finds each project whose identifier for the integration has that value. More than one project can match. For PagerDuty, it verifies the signature against the secret of each matched project.
5. It finds the Imbi user who caused the event, when it can (see Attribution).
6. It resolves the event type with the Event Type Selector.
7. It records one events row for each matched project. The row goes to the Iggy stream events, topic gateway, and the sink writes it to the ClickHouse events table.
8. It evaluates the filter expression of each rule. See Webhook Rule Filter Expressions.
9. For each matched project, it runs each matched rule in rule order.
10. It records the outcome of each action (succeeded, failed, or skipped) on the events row.

The Webhook History of a webhook shows these rows.

Set up a webhook¶

Do these steps one time for each source.

1. Make sure that the integration has the webhook-actions capability on. See Integrations and Plugins.
2. Make sure that each project has its identifier for the integration, for example the GitHub repository id.
3. Open Admin > \ Admin > Webhooks and create a webhook. See Webhooks for the form.

4. Set the fields of the integration binding:

   Field	What to enter
   Integration	The integration that sends the webhook
   Identifier Selector	A JSON pointer into the body, for example /repository/id
   User Subject Selector	A JSON pointer to the id of the external user, for example /sender/id
   User Type Selector	Optional. A JSON pointer to the account type, for example /sender/type. A value of Bot skips the user lookup
   Identity Integration Slug	Optional. The integration that maps the external user to an Imbi user
   Event Type Selector	Optional. A header name, for example x-github-event, or a JSON pointer that starts with /
   Secret	The signing secret. For GitHub, use the secret of the GitHub hook

5. Add the rules. Each rule has a Filter Expression (CEL), a Handler, and a Handler Config (JSON). Rules run in the order of the list.

6. Save the webhook. Copy its URL into the source system.

The selectors of the binding read the body directly (/repository/id). The selectors in a handler_config read the event context, so the body is under /payload (/payload/repository/id).

The person who saves the rules is accountable for them. An agent task that a rule makes belongs to that person.

Signature verification¶

Each plugin declares its signature with WebhookSignature (the signature() class method of its webhook-actions capability). The table shows the first-party plugins. A plugin that declares no signature gets no verification.

The signature is an HMAC-SHA256 of the raw body. The header can hold more than one signature, separated by commas. One match is sufficient.

• When a secret is set, a delivery with a missing or wrong signature gets 204, and the gateway records nothing.
• When a GitHub webhook has no secret, the gateway processes its deliveries without verification. It logs a warning one time for each webhook.

The filter variable github_signature_verified is true only for a GitHub delivery that verified. The actions create_agent_task and start_workflow run only for a signed delivery: a GitHub delivery that verified, or a delivery to a project whose identifier has a secret.

Attribution¶

The gateway reads the external user id with the User Subject Selector. It then asks imbi-api for the Imbi user with that identity. It asks the Identity Integration Slug when you set it. Otherwise it asks the webhook's own integration, when that integration has the identity capability on.

The resolved user goes into attributed_to, and into created_by of a release that an action makes. When the gateway finds no user, or two different users, it leaves the delivery unattributed.

Handlers¶

A rule's Handler has the form <plugin slug>#<action name>, for example gateway-actions#create_release. Each part starts with a lowercase letter. After that, the plugin slug uses lowercase letters, digits, and hyphens, and the action name uses lowercase letters, digits, and underscores.

imbi-api checks the handler when you save the rule. It refuses a handler in another form, and a plugin or action that is not in its plugin registry. imbi-api does not load the gateway-actions plugin, so it checks only the form of a gateway-actions handler.

The gateway resolves the handler again when a delivery arrives. When the handler has another form, the plugin or the action does not exist, or the handler_config is not valid, the gateway logs an error and skips that rule. The other rules of the webhook still run.

When a plugin declares credentials, its actions get the credentials of the webhook's integration. When the integration has no credentials, the gateway skips the rule.

To write a new action, see Webhook Actions Capability.

Built-in actions¶

The gateway includes the plugin gateway-actions. It needs no credentials.

In the tables below, a pointer is a JSON pointer into the event context, and a CEL field is a CEL expression over the event context. The webhook body is /payload in a pointer and payload in CEL. CEL fields in a handler_config can use substring(). See Webhook Rule Filter Expressions.

update_project¶

handler_config is a list. Each item adds one value to the project with a JSON Patch add operation.

[{"path": "/description", "from": "/payload/repository/description"}]

create_release¶

You must set committish_expression, version_expression, or both. When neither resolves, the action does nothing. imbi-api finds the commit of a tag when you set only version_expression.

The create is idempotent. Two rules that announce the same release make one release.

{
  "committish_expression": "substring(payload.deployment.sha, 0, 7)",
  "version_expression": "payload.deployment.ref",
  "title_selector": "/payload/deployment/description"
}

add_deployment_event¶

When no release matches, the action records the deployment on the project and environment without a release. The deployment-sweep maintenance operation attaches the release later. A state that is not in the mapping is skipped.

{
  "environment_selector": "/payload/deployment/environment",
  "committish_expression": "substring(payload.deployment.sha, 0, 7)",
  "version_expression": "payload.deployment.ref",
  "status_selector": "/payload/deployment_status/state",
  "external_run_url_selector": "/payload/deployment_status/log_url"
}

publish_release¶

The action runs only when the state maps to success. It makes the remote release for the tag, for example the GitHub Release. When imbi-api has no release for the tag (404), or the release is blocked (409), the action does nothing.

block_release¶

The action runs only when the state maps to failed (failure or error). The state inactive does not block a release.

update_release_drift¶

Use it with a GitHub push delivery. The action skips a push to any other ref, and a push without a full before and after commit. It sends before and after to imbi-api, which reads the changed notes and marks the releases. See Drift.

ingest_sbom¶

When no release has the tag and committish_expression is not set, the action drops the SBOM and logs a warning.

{
  "version_expression": "payload.ref_name == \"main\" ? substring(payload.sha, 0, 7) : payload.ref_name",
  "sbom_selector": "/payload/sbom",
  "committish_expression": "payload.sha"
}

create_agent_task¶

The action runs only for a signed delivery with a valid delivery id. A redelivery makes no second task. See Agent Tasks.

start_workflow¶

Do not write this rule. imbi-workflows writes it when you activate a workflow with a webhook trigger. The action runs only for a signed delivery with a valid delivery id. See Workflows.

Plugin actions¶

Other plugins add actions. These are the actions of the plugins in this repository:

The pointer defaults read the GitHub payload, for example /payload/repository/full_name. For each plugin, see GitHub and SonarQube.

Settings¶

The full list is in Configuration. The gateway needs these:

The service account¶

The actions call imbi-api as the imbi-gateway service account. Its role, also imbi-gateway, grants project:read, project:write, user:read, agent_task:create, and workflow:run.

• imbi-api setup makes the account and its API key. When IMBI_GATEWAY_API_TOKEN is set, setup uses that value. When it is not set, setup prints a new key one time.
• In the all-in-one image (IMBI_SERVICE=all), the entrypoint makes the key when the variable is not set.
• The account must be a member of each organization that has webhooks, with the imbi-gateway role. For another organization, run imbi-api setup-service-accounts --organization <organization slug>.

Endpoints¶

The counter imbi.gateway.deployment_events counts the outcome of each add_deployment_event call.