Pull request integration

Native pull request integration runs Maestro tests asynchronously and blocks merges on failures. Supports GitHub Enterprise.

Native pull request integration allows you to run Maestro Flows asynchronously on every code change. You can configure it to block pull requests from being merged if test failures are detected.

Maestro Cloud Plan required. Pull request integration is available on the Maestro Cloud Plan.

Maestro Cloud currently supports native pull request integration for:

• GitHub

• GitHub Enterprise only.

1

Trigger uploads on every pull request

You must configure your CI environment to trigger a Maestro Cloud upload for every pull request. You can accomplish this by using one of the following options:

GitHub Actions

Trigger your workflow on pull_request events against your baseline branch.

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

Maestro CLI

Add the --async flag and PR-specific metadata to your maestro cloud command.

maestro cloud \
  --async \
  --api-key <YOUR_API_KEY> \
  --branch <BRANCH_NAME> \
  --repo-owner <REPO_OWNER> \
  --repo-name <REPO_NAME> \
  --pull-request-id <PR_ID> \
  --commit-sha <COMMIT_SHA> \
  --app-file <APP_FILE> --flows .maestro/

The following table describes each one of the required flags you must inform.

Argument	Description
--branch	The name of the git branch being tested (e.g., feature-branch). Maestro uses this to group results by branch in the console.
--repo-owner	The owner (individual or organization) of the repository on GitHub. Required for posting status checks.
--repo-name	The name of the repository. Combined with --repo-owner, this identifies the target project for integration.
--pull-request-id	The number of the pull request. Essential for linking the test run to a specific PR and enabling automated comments.
--commit-sha	The full 40-character SHA of the commit. This ensures test results are associated with the exact state of the code.

API

If using the upload API directly, include the following fields in the JSON payload:

• branch

• repoOwner

• repoName

• pullRequestId

• commitSha

The following table describes each one of the required fields you must inform.

Field	Description
branch	The name of the git branch being tested (e.g., feature-branch). Maestro uses this to group results by branch in the console.
repoOwner	The owner (individual or organization) of the repository on GitHub. Required for posting status checks.
repoName	The name of the repository. Combined with --repo-owner, this identifies the target project for integration.
pullRequestId	The number of the pull request. Essential for linking the test run to a specific PR and enabling automated comments.
commitSha	The full 40-character SHA of the commit. This ensures test results are associated with the exact state of the code.

2

Grant access to pull requests

Maestro requires permission to update pull request statuses. To accomplish this, you must install the Maestro Cloud app and grant access to your repositories to the desired repositories.

3

Test the integration

Once configured, open a pull request. The Maestro Cloud status check appears in the checks section. A passing check indicates all Flows ran successfully, while a failing check indicates that at least one Flow failed.