Deployment events

Triggering tests via API

A mabl deployment event triggers a run of all plans in a workspace that match the specified conditions, such as application, environment, and plan label. This action can start multiple plans at once or trigger a specific plan to run in just one of its configured environments. Deployment events are a powerful feature, making it possible to trigger test runs from the CLI and integrate mabl tests into an existing CI/CD workflow.


Deployment Event API

Deployment events are created using the Deployment Event API, which has two endpoints:

There are a few different ways you can trigger a deployment event, including:

This guide outlines how to create a deployment event in the mabl app to illustrate how a deployment event works.

Configuring plans for deployment events

Deployment events trigger tests at the plan level. In order for a plan to be triggered by a deployment event, it must meet the following criteria:

  • The plan is active.
  • The plan accepts a deployment trigger: edit plan > triggers > run on deployment.
  • At least one of the tests in the plan is turned on. If a plan is active, but all of the tests in the plan are turned off, the plan does not run.
Plan with the correct settings to be triggered by a deployment event

Plan with the correct settings to be triggered by a deployment event


Disabling plans

If you want to exclude a plan from running in the deployment event, you can disable it from the Plan page by toggling it off. The plan will not be able to be run until it is re-enabled.

Trigger a deployment event

To create a deployment event in the mabl app, go to the New Deployment page:

  1. On the mabl home page, click on the "New" button in the top-left corner.
  2. Select "deployment" to open the New Deployment page.

The New Deployment page

  1. Select the environment, the application, or both environment and application from the dropdowns
  2. Optionally, you may choose one or more plan labels to target specific plans.


Plan labels

You can get the most out of deployment events by leveraging plan labels to define specific test suites, such as regression, targeted regression, smoke, or a certain functionality or feature area.

  1. The New Deployment page includes additional optional settings for URL overrides, browsers, credentials and headers.
  2. Click the "Trigger Deploy" button to create the deployment event.

An output page for the deployment event shows the current status of the plan runs that were triggered.


The Deployment Event Output page


Deployment events count toward monthly quota

Depending on the arguments that you provide, deployment events are capable of triggering a lot of plan runs that will count toward your allotted monthly quota of cloud runs.

If you want to confirm how many plans will run as a result of a deployment event, you can follow the steps outlined in the Previewing the deployment event section.

Curl command builder

You can find another resource for creating deployment events on the API page: Settings > APIs. Below the sections for managing API keys and working with the mabl CLI, there is a section called API documentation. This section includes a curl command builder for building requests to Deployment Event API endpoints:

  • Create deployment event
  • Get results from a deployment event
Curl command builder on the API page

Curl command builder on the API page

Create deployment event

When you select the environment, application, and plan labels for the deployment event, a curl command appears at the bottom of the page. Notice that the curl command uses unique IDs to specify the environment and application. These IDs are known as mabl resource IDs.

To create the deployment event, copy and paste the curl command into your terminal and press enter.


Deployment event ID

Running the curl command returns a JSON response that includes the ID of the deployment event, which ends in -v. You can use the deployment event ID to make a separate call to the Deployment Events API to retrieve results from the deployment event.

Get results from a deployment event

Paste the deployment ID to generate a curl command for retrieving the status of plans that were triggered as a result of the deployment event.

Previewing the deployment event

If you want to see what plans would execute in a deployment event without the risk of accidentally triggering dozens of plans, follow these steps for previewing a deployment event:

  1. Go the to API page: Settings > API
  2. In the API documentation section, select "Create deployment event"
  3. Select your target environment and/or application.
  4. Add optional settings as needed, including plan labels, URL overrides, and credentials.
  5. Copy the generated curl command.
  6. Open a terminal window on your machine.
  7. Paste the curl command into the terminal.
  8. Replace the URL with
  9. Press enter to see the preview.

The "triggered_plan_run_summaries" section in the JSON response shows the plans that would run if you triggered this deployment event. Consider the following response:


This sample response lists seven plan IDs, which means that seven plans would run as a result of this deployment event.

Learn more

Understanding deployment events is a crucial step toward achieving coverage at scale. To take your knowledge a step further, consider checking out the following guides on implementing deployment events into your testing workflow:

Deployment events API webinar

Watch this webinar featuring mabl's Matthew Stein and James Baldassari for a detailed look at the deployment events API and how to incorporate it into your mabl plans.