Ask the change agent of a pull request or a revision to validate a stage, or send it a command

Sends one event to the change agent of a pull request or of a revision, which is a deployed commit named by
a commit reference. Each change has one long-lived change_validation agent, and this call is the only
way to create or message it.

  • stage.requested asks the agent to validate one stage of the repository's policy at a head commit. The
    first one for a change creates its agent, and the caller becomes the agent's principal for the rest of
    its life.
  • command messages an existing pull request's agent.
  • pull_request.merged says the pull request of an existing agent merged. When the policy read at the
    merge commit sets merge_mabl_branches, mabl merges the pull request's mabl branch into master, as the
    caller and fast-forward only.

Every caller, not only the first, must be able to do everything the agent does, and a person must hold a
role in the workspace. Requests for one stage are ordered by event.occurred_at, and the response's
event says what became of this one. A retry of any call is safe.

Branch on error_code in an error body: invalid_request (400), feature_disabled,
principal_too_narrow and principal_gone (403), no_change_agent (404), change_agent_closed,
too_many_stages and another_repository (409), and agent_stopping (503), which a client retries. A
body that breaks the request schema is refused with a 400 that carries no error_code.

For how the calls fit together and what to do about each error, see
Run change validation from your own CI.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

One event for the change agent of a pull request or a revision.

string
required

The workspace the agent runs in

reference
object
required

The change. A pull request, of type pull_request, its id lowercase as host/owner/repo#n or, on Azure DevOps, host/org/project/_git/repo#n, with n carrying no leading zero. Or a revision, of type commit, its id the commit's full sha, 40 lowercase hex characters. It is the change agent's only reference: the agent takes no other, such as the ticket the pull request closes.

string
length ≤ 20000

What changed. The agent treats it as untrusted text

string
length between 1 and 256

Required on a command, unique per command. Ignored on a stage request, which mabl keys from its stage, head, base and occurred_at

boolean

On a stage request, stored with the stage's request: when true, the stage's checks at that head report what would run and never start a run; when false, they run. Absent, the stage follows the agent's setting, which the request that created the agent set (false when that request didn't send it either). A later request for the stage sets it anew; a head whose runs already started keeps them. Ignored on a command

event
object
required
Responses

Language
Credentials
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json