---
title: "corestack_deployments_rehearse"
url: https://docs.corefinity.com/mcp/tools/corestack_deployments_rehearse
type: tool
last_updated: 2026-11-13
feature: deployment-pipeline
related:
  - https://docs.corefinity.com/api/reference/deployments/start-site-deployment-rehearsal.md
  - https://docs.corefinity.com/guides/sites/code-and-deployments/pipeline-stages.md
---
# corestack_deployments_rehearse

**Rehearse a pipeline.** Rehearse a deployment pipeline on a non-production environment of the site: build, upload into a scratch release and run the platform step and database stage against that environment's services, switching nothing. Follow it with corestack_deployments_rehearsal_get. Scope: exec. Long-running: answers with a task.

- Scope: `exec`
- Runs as a task: yes

## When to use it

Rehearse a deployment pipeline on a non-production environment of the site before deploying it: the build, the upload into a scratch release, the shared files, the platform step and the database stage run against that environment's own services, and nothing is switched. `binding_id` is this environment's binding, or another environment's of the same site (its stages run here, with this environment's repository, variables, registry secrets and services). `proposal` rehearses unsaved changes — units by name (`build`, `database`, `post_deploy`, `settings`), each as `corestack_deployments_pipeline_stage_update` or `corestack_deployments_pipeline_settings_update` takes it — checked like a save and never saved. Lines that reach third parties (`curl`, `wget`, `scp`) are skipped and listed. Follow the task, or read the result with `corestack_deployments_rehearsal_get`; a failure names the step and the reason.

Check first with `corestack_deployments_shared_files_check` (`for: rehearsal`, on the environment you rehearse on) and tell the person what it found: a rehearsal stops at linking shared files when the settings file its platform needs is in none of the places it looks, unless the repository includes it, which no check can see before the build; the check names each missing file and where to create it over SFTP or SSH. It only advises: a rehearsal is never refused for its answer, so start when the person says so, whatever it found.

The same action in the public REST API, with the same checks, refusals and scope: `POST /api/corestack/sites/{site}/deployments/rehearsals` (202 with the rehearsal).

## Inputs

- `site_id` (integer, ≥ 1, required): The non-production environment to rehearse on.
- `binding_id` (integer, ≥ 1, required): This environment's binding, or another environment's of the same site (its stages run here).
- `ref` (string, up to 255 characters): A branch or a commit SHA; the repository's branch head when left out.
- `proposal` (object): Unsaved units by name (build, database, post_deploy, settings), each as the stage or settings update takes it; checked, never saved.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "binding_id": {
      "description": "This environment's binding, or another environment's of the same site (its stages run here).",
      "minimum": 1,
      "type": "integer"
    },
    "proposal": {
      "description": "Unsaved units by name (build, database, post_deploy, settings), each as the stage or settings update takes it; checked, never saved.",
      "type": "object"
    },
    "ref": {
      "description": "A branch or a commit SHA; the repository's branch head when left out.",
      "maxLength": 255,
      "type": "string"
    },
    "site_id": {
      "description": "The non-production environment to rehearse on.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "binding_id"
  ],
  "type": "object"
}
```

## Refusals

- `forbidden`: the person's role lacks the Edit Environment Deployment Pipeline permission (a rehearsal runs the
  pipeline's lines). The message names it and says an owner of the company can grant it in Roles; `details.permission`
  is `editEnvironmentDeploymentPipeline`. Nothing is changed.
- `switched_off`: rehearsals are paused by Corefinity (the `exec` switch); try again later.
- `rehearsal_production`: a production environment is never rehearsed on; rehearse on a staging environment of the site.
- `busy`: a rehearsal, deployment or other change of this environment is running; wait for it to finish, then call again.
- `pipeline_untranslated`: the pipeline carried over from CoreStack Enterprise is not translated yet; contact support.
- `pipeline_review_pending`: pipeline lines carried over are waiting for review; accept them (corestack_deployments_carryover_accept) first.
- `pipeline_switched_off`: the deployment pipeline this binding needs is switched off; the person should contact Corefinity.
- `pipeline_classic`: the binding is not in build, database and post-deploy stages yet; it cannot be rehearsed.
- `pipeline_locked`: Corefinity has locked this pipeline; the proposal cannot be checked against it.
- `tunnels_switched_off`: the build needs tunnels, which are switched off right now; try again later.
- `invalid_arguments` with `detail_reason` `no_repository` (message: "Connect a repository first"): the site has no repository connected, so there is nothing to rehearse; connect one with corestack_deployments_repository_set first. Nothing is created. The `reason` is the one this refusal has always answered; `detail_reason` names it.
- `not_available`: this environment has no binding the other environment's pipeline can run on.
- `line_credentials`: a proposed line holds a credential; move it into a secret variable (corestack_deployments_variable_set).
- `line_own_shell`: a proposed line is only `cd <dir>` and a later line follows it; each line runs in its own shell, so join them on one line with `&&`.
- `line_too_long`: a proposed line is too long; shorten it.
- `too_many_lines`: a proposed stage has too many lines.
- `managed_elsewhere` (message: "This site is managed by another control panel"): another control panel manages this site, so use that control panel for it. This is refused before anything else about the site, as in the Control Panel and the API. Nothing was done.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_deployments_rehearse",
  "arguments": {
    "site_id": 4212,
    "binding_id": 1841,
    "proposal": {
      "database": {
        "lines": ["wp option get siteurl"]
      }
    }
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_deployments_rehearse with site_id 4212, binding_id 1841, proposal {"database":{"lines":["wp option get siteurl"]}}. (Rehearse a pipeline.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/corestack/sites/{site}/deployments/rehearsals](https://docs.corefinity.com/api/reference/deployments/start-site-deployment-rehearsal.md)
- Guide: [Pipeline](https://docs.corefinity.com/guides/sites/code-and-deployments/pipeline-stages.md)
