Skip to main content

Generating Custom GitHub Events

Eva Ferreira
  • Updated

You can use a custom RepositoryDispatch event to trigger custom GitHub workflows based on mabl insights, such as when a plan starts failing after deployment. Each insight maps to one dispatched event. See the article on insights for a full list of mabl behaviors that generate insights.

This article explains how to configure custom GitHub events based on mabl insights.

Set up the integration

Follow the GitHub integration setup instructions to install the integration. When configuring the integration, make sure to enable Create RepositoryDispatch events for mabl insights.

The GitHub integration must also be configured in your primary workspace. If your plans run in a non-primary workspace, dispatches will not route to GitHub.

Add mabl events to your GitHub Workflows

Copy the following example YAML file to .github/workflows/trigger-on-mabl-insight.yml in the GitHub repository that is used in your mabl CI/CD integration.

name: Process mabl insight
# This workflow is triggered on new mabl insights
on: [repository_dispatch]

jobs:
  build:
    name: Process mabl Insight
    runs-on: ubuntu-latest
    steps:
      # Add you custom logic below this line - example below
      - name: Print event type
        run: echo 'event_type:${{ github.event.event_type }} name:${{ github.event_name }}' # Will be 'mabl_insight'
      - name: Print Insight details
        run: echo 'id:${{ github.event.client_payload.insight.id }} type:${{ github.event.client_payload.insight.insight_type }}'
      - name: Print Insight payload as JSON
        run: echo 'insight payload: ${{ toJson(github.event.client_payload.insight) }}'

Run tests

For mabl to dispatch events to your GitHub repository, your mabl deployment events must include a GitHub commit hash. mabl uses the commit hash to identify which GitHub repository to dispatch to. Without it, no dispatch fires.

Pass the commit hash when you create the deployment event:

  • mabl CLI: include --revision {commit-sha} in your mabl deployments create command.
  • Deployments API: include the revision field in the request body.
  • run-mabl-tests GitHub Action: the Action passes github.sha automatically. No additional configuration is required.

Example using the mabl CLI:

mabl deployments create \
  --application-id {app-id} \
  --environment-id {env-id} \
  --revision {commit-sha}

Example event payloads

When an insight is generated in mabl based on mabl tests run against this repository, the code in the aforementioned workflow will be triggered. The mabl insight is passed into the workflow as the github context variable with the name github.event.client_payload.insight.

mabl_insight is the only event type mabl sends. If your workflow filters on other type names, such as mabl-test-run-completed, mabl-deployment-verification-completed, or mabl-test-failure, the workflow will not match, even when mabl dispatches an event. Use on: [repository_dispatch] with no filter, or types: [mabl_insight].

A sample insight payload follows:

{
  "id": "jHn6br1LOm10MwEsPjURxQ-i",
  "workspace_id": "nKqPRcj1Rrm8zqgb3KeTSQ-w",
  "environment_id": "otnJ3IeoWm4zwmoVFz7ppA-e",
  "application_id": "RePxEygYbhJdPbjgGqywPTw-a",
  "run_policy_id": "yWud5dtC7OEPXp2akr6Dzg-p",
  "plan_id": "yWud5dbAraEPPjSRkr6Dzg-p",
  "created_time": 1579186926230,
  "last_updated_time": 1579186927108,
  "type": "occurrence_run_policy_execution_system_event",
  "current_state": "occurrence",
  "status": "info",
  "category": "run_policy_execution_system_event",
  "context": {
    "triggering_resource_type": "user",
    "triggering_resource_id": "dXAi-GwSvITmihOKLu5k0KQ",
    "system_event": "run_policy_execution",
    "trigger_type": "schedule"
  },
  "plan_run_id": "iG8I5bI8lpQm53yJRHA9JA-pr",
}

Related articles