Cloud Build integration

Use the mabl Google Cloud Build integration to automatically trigger mabl plans associated with a specific mabl environment and/or application to run as a stage in your Cloud Build pipeline.

With this integration you can:

• Run mabl tests in your CI/CD pipeline, or in the mabl cloud
• See mabl test result summaries in your build logs
• Trigger build failure if mabl tests fail
• Link to Cloud Build logs from your mabl Deployments screen

Additionally, browser test runs can be run fully within Cloud Build, though these will only display results in Cloud Build, rather than in the mabl cloud.

Setup

Add mabl to your build to trigger cloud runs

In the cloudbuild.yml file for your pipeline, add a step to create a mabl deployment event. Deployment events trigger mabl cloud runs for the plans that match the selectors you provide, such as application, environment, or plan labels. 

Use the example shown in the following code block as a template:

# Add this to your "steps:" block
- name: 'mablhq/mabl-cli'
  id: 'Validate app quality'
  # Add the arguments you'd pass to the CLI, one at a time. Don't include the "mabl" prefix.
  args: ['deployments','create',
  '--application-id', '<YOUR-APPLICATION-ID>',
 '--labels','<YOUR-LABELS>'
  '--await-completion']
  # Enable so mabl can link back to your build from the mabl app
  automapSubstitutions: true 
  secretEnv: ['MABL_REST_API_KEY']

availableSecrets:
  secretManager:
  # Store your mabl CLI key securely in Cloud Secret Manager
  - versionName: projects/<YOUR-PROJECT>/secrets/cloud-build-mabl-rest-api-key/versions/latest
    env: 'MABL_REST_API_KEY'

The args field takes an array of options: 

• --application-id: run plans associated with the specified application
• --labels: run plans that match the specified label(s).
• --await-completion: await completion of the mabl plan runs and display the outcome. If cloud plan runs fail, return a non-zero bash exit code and fail the cloud build step.

For a complete list of options, see the article on the mabl deployments create CLI command.

To use this example step in your build, update the following placeholders:

• <YOUR-APPLICATION-ID>: update to the application ID of the mabl plans you want to run
• <YOUR-LABELS>: update to a space-delimited list of plan labels
• <YOUR-PROJECT>: update to the Google Cloud project ID where your Cloud Secret Manager is located.
• cloud-build-mabl-rest-api-key: update to the secret name holding your mabl API key

Add mabl to your build to trigger "local" test runs

You also can run mabl tests fully within Cloud Build, meaning the tests will be run headlessly with Cloud Build, rather than running tests on the mabl cloud. This is also known as a "local" test run. Note local test runs and their results will not be visible in the mabl cloud.

To run tests fully within Cloud Build, use the above example and changename: 'mablhq/mabl-cli'to name: 'mablhq/mabl-cli-chromium' so that your build uses the mabl image that includes Chromium.

Additionally, use the arguments in the args array for the  mabl tests run --headless --id <test-id>command . See mabl tests run --help for all available options. Note that only executing test runs is supported, rather than plan runs.

Adding mabl API Keys to your build

Use the MABL_REST_API_KEYenvironment variable to pass credentials to the mabl API. The integration automatically detects this key and uses it to authorize all CLI commands.

As a security best practice, use Google Cloud Secret Manager to hold secrets like API keys. The example step is configured to use the cloud-build-mabl-rest-api-key secret stored in the project named YOUR-PROJECT.

See the Cloud Build Using Cloud Secrets documentation for full details on how to access Cloud Secret Manager secrets from your build.

Alternatively, you can hardcode the API key in the build file as part of your build step definition, as shown in the following code block. This method is not considered a security best practice because anyone that views the build file will see the plaintext API key.

env:
- "MABL_REST_API_KEY=<YOUR-SECRET-KEY>"

Results

After the build completes, you can see the results of your mabl tests in the build summary:

See mabl test results in the build logs

If the --await-completion CLI flag is passed as part of your args: values, the test result summary will show output as an ASCII table at the end of the test runs in your build log, as shown in the following image.  To view the full, detailed results, click on the link to view output in the app.

Build logs include a link to view output in mabl

The deployment details page in mabl indicates that the deployment was triggered by a Cloud Build and includes the build ID and a deep link back to the Cloud Build logs.

Details page for a deployment triggered by a Google Cloud Build