Start a pipeline rehearsal
Runs a pipeline's stages on a staging environment without changing what the environment serves, to show whether a deployment would succeed. Only one rehearsal of an environment runs at a time, and a production environment is never rehearsed on. Your role needs the Edit Environment Deployment Pipeline permission, and the token the deploy ability as well as the exec scope: a rehearsal builds and runs a deployment.
- Needs
deployas well: Always.
Path parameters
The id of a site row. A website's production site and each of its environments has its own id. Digits only. At least 1.
Body
This environment's pipeline, or one of another environment of the same site, whose stages then run here. At least 1.
Stages or settings that are not saved, by name (build, database, post_deploy, settings), each as its save takes it. Checked and rehearsed, never saved.
A branch or a commit to build. The head of the repository's branch when left out. Up to 255 characters.
Returns
202 The rehearsal started. Poll the operation until it finishes.
Fields of the 202 answer
Fields
The pipeline of this environment the rehearsal runs on.
Present when one line failed. Its stage, index and text.
Present on a rehearsal that failed. What went wrong, with its message.
Each part of the rehearsal with where it is, such as pending or skipped.
What the rehearsal leaves out, each with why.
running until the rehearsal has finished, then how it ended, such as passed.
If it is refused
| Status | Reason | What to do |
|---|---|---|
401 | none | Send a valid token as Authorization: Bearer <token>. |
403 | company_unavailable | Your company is unavailable. |
403 | forbidden | The person is not allowed to do this. |
403 | scope_required | Use a token with the scope named in scope. |
403 | two_factor_required | Turn on two-factor on your account, then send again. |
404 | feature_off | This feature is not on for your organisation yet. |
409 | deployment_running | A deployment of the environment is running, or a stopped one is still being cleaned up. Wait for it to finish, then try again. |
409 | rehearsal_production | Rehearse on a staging environment of this site first. |
422 | invalid | Fix the field named in field; errors says why. |
429 | rate_limited | Wait for the seconds in Retry-After. |
502 | none | Read the message; it says what happened. |
503 | switched_off | Corefinity has switched this action off for the moment. Try again later. |
Reasons are listed by name in Errors and refusals.
The same task elsewhere
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/deployments/rehearsals \
-H "Authorization: Bearer $COREFINITY_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"binding_id": 2211
}'use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('COREFINITY_TOKEN'))
->acceptJson()
->post('https://manage.corefinity.com/api/corestack/sites/1042/deployments/rehearsals', [
'binding_id' => 2211,
]);
$data = $response->json();const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/deployments/rehearsals', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
binding_id: 2211,
}),
});
// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);import os
import requests
res = requests.post(
"https://manage.corefinity.com/api/corestack/sites/1042/deployments/rehearsals",
headers={
"Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
"Accept": "application/json",
},
json={
"binding_id": 2211,
},
)
data = res.json() if res.content else None{
"rehearsal": {
"binding_id": 2211,
"finished_at": null,
"id": 77,
"per_stage": {
"build": "skipped",
"database": "skipped",
"platform_step": "pending",
"shared_files": "pending",
"upload": "pending"
},
"skipped": [],
"started_at": "2026-11-09T10:42:07Z",
"state": "running"
}
}{
"message": "Unauthenticated."
}{
"code": "company_unavailable",
"message": "Your company is unavailable.",
"reason": "company_unavailable"
}{
"code": "feature_off",
"message": "Not found.",
"reason": "feature_off"
}{
"code": "deployment_running",
"message": "A deployment is running. Wait for it to finish, or stop it from its page.",
"reason": "deployment_running"
}{
"code": "invalid",
"errors": {
"binding_id": [
"Choose the pipeline to rehearse."
]
},
"field": "binding_id",
"message": "Choose the pipeline to rehearse.",
"reason": "invalid"
}{
"code": "rate_limited",
"message": "Too many requests. Try again in 60 seconds.",
"reason": "rate_limited",
"retry_after_seconds": 60
}{
"message": "GitLab did not answer. Try again."
}{
"code": "switched_off",
"message": "Site commands are switched off at the moment",
"reason": "switched_off",
"switch": "exec"
}Try it is off for this endpointIt runs commands on a live site. Copy the request and run it yourself when you are sure.