Skip to content

feat(cube-cli): add data-model enable-branch / disable-branch commands #11433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paveltiunov wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(cube-cli): add data-model enable-branch / disable-branch commands #11433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs-mintlify/admin/deployment/environments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,14 @@ regardless of user activity.
<img src="https://ucarecdn.com/e0dcce34-a53a-4087-b021-25dbaf730a92/" />
</Frame>

The same toggle is available in the [CLI][ref-cli] and the [Control Plane
API][ref-control-plane-api-staging], so it can be scripted, e.g. from CI:

```bash
cube data-model enable-branch DEPLOYMENT_ID BRANCH_NAME
cube data-model disable-branch DEPLOYMENT_ID BRANCH_NAME
```

### Resources and costs

Staging environments run on Shared deployments, incurring [relevant
Expand Down Expand Up @@ -115,4 +123,6 @@ credentials**][ref-credentials].
[ref-overview]: /admin/connect-to-data/visualization-tools
[ref-credentials]: /admin/connect-to-data/visualization-tools
[ref-version]: /admin/deployment#cube-version
[ref-version-channel]: /admin/deployment#update-channels
[ref-version-channel]: /admin/deployment#update-channels
[ref-cli]: /reference/cli
[ref-control-plane-api-staging]: /reference/control-plane-api#buildapiv1deploymentsdeployment_idbranchesstaging-environment
16 changes: 15 additions & 1 deletion docs-mintlify/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ Run `cube <command> --help` for the full options of any command.
| `logs` | Tail deployment pod logs (`--pod`, `-c/--container`, `--source production\|dev`) |
| `regions` | List available deployment regions |
| `github` (`gh`) | GitHub integration: `status`, `installations`, `repos`, `branches`, `connect` |
| `data-model` | Data model files and Git workflow: `list`, `get`, `put`, `delete`, `rename`, `file-hashes`, `branches`, `create-branch`, `dev-mode`, `commit`, `pull`, `merge`, `merge-to-default` |
| `data-model` | Data model files and Git workflow: `list`, `get`, `put`, `delete`, `rename`, `file-hashes`, `branches`, `create-branch`, `enable-branch`/`disable-branch`, `dev-mode`, `commit`, `pull`, `merge`, `merge-to-default` |
| `environments` | Deployment environments and environment tokens |
| `variables` | Deployment environment variables |
| `folders`, `workbooks`, `reports`, `workspace` | Workspace content management |
Expand All @@ -178,6 +178,19 @@ cube data-model merge-to-default DEPLOYMENT_ID --branch my-branch -m "add orders

`merge-to-default` merges into the deploy branch and rebuilds production.

`enable-branch` keeps a shared branch's [staging environment][ref-staging-env]
always active, so it stays queryable without anyone viewing the branch in the
UI — useful for running tests against a branch from CI. `disable-branch` reverts
to the default, where the environment is only active while viewed.
`cube data-model branches DEPLOYMENT_ID` shows the current state per branch, and
`cube environments list DEPLOYMENT_ID --type staging` lists the enabled ones with
their API credentials.

```bash
cube data-model enable-branch DEPLOYMENT_ID my-branch
cube data-model disable-branch DEPLOYMENT_ID my-branch
```

## Environment variables

| Variable | Description |
Expand All @@ -200,3 +213,4 @@ or explicitly with `CUBE_NO_TELEMETRY=1` (or the legacy `CUBEJS_TELEMETRY=false`

[ref-api-keys]: /admin/account-billing/api-keys
[ref-rest-api]: /reference/core-data-apis/rest-api/index
[ref-staging-env]: /admin/deployment/environments#staging-environments
63 changes: 63 additions & 0 deletions docs-mintlify/reference/control-plane-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,67 @@ Example response:
```


### `/build/api/v1/deployments/{deployment_id}/branches/staging-environment`

Send a `PUT` request to enable or disable a branch, i.e. to control whether its
[staging environment][ref-environments-staging] stays always active. Disabled
(the default), a staging environment is only active while the branch is viewed
in the Cube UI; enabled, it remains active and accessible regardless of user
activity, and it is reported by
[`/api/v1/deployments/{deployment_id}/environments`](#apiv1deploymentsdeployment_idenvironments)
as a `staging` environment.

Only shared branches can be enabled — personal development branches and the
production branch are rejected.

<Info>

Note the `/build` prefix: data model and branch endpoints are served by the
build API.

</Info>

Path parameters:

| Parameter | Description |
| --- | --- |
| `deployment_id` | The deployment ID |

Body parameters:

| Parameter | Description | Required |
| --- | --- | --- |
| `enabled` | `true` enables the branch, `false` disables it | Yes |
| `branchName` | Name of the branch to update | One of `branchName` or `branchId` |
| `branchId` | ID of the branch to update, as returned by `GET /build/api/v1/deployments/{deployment_id}/branches` | One of `branchName` or `branchId` |

Example request:

```bash
curl -X PUT \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"branchName": "staging", "enabled": true}' \
"https://YOUR_CUBE_CLOUD_HOST/build/api/v1/deployments/123/branches/staging-environment"
```

Example response:

```json
{
"data": {
"id": 456,
"name": "staging",
"parentBranch": "main",
"lastHash": "9f2c1ab",
"isStagingEnvironmentEnabled": true
}
}
```

The same operation is available in the [CLI][ref-cli] as
`cube data-model enable-branch` / `cube data-model disable-branch`.

### `/api/v1/audit-logs/export`

Send a `GET` request to export [audit log][ref-audit-log] events as a CSV
Expand Down Expand Up @@ -262,6 +323,8 @@ curl \
[ref-metadata-api]: /reference/core-data-apis/rest-api/reference#metadata-api
[ref-deployments]: /admin/deployment
[ref-environments]: /admin/deployment/environments
[ref-environments-staging]: /admin/deployment/environments#staging-environments
[ref-cli]: /reference/cli
[ref-api-keys]: /admin/account-billing/api-keys
[ref-security-context]: /docs/data-modeling/access-control/context
[ref-audit-log]: /admin/monitoring/audit-log
2 changes: 1 addition & 1 deletion rust/cube-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ Every endpoint of the Console Server public API is covered:
| `regions` | list available deployment regions |
| `logs` | tail deployment pod logs (`--pod`, `-c/--container`; defaults to the Cube API container) |
| `github` (`gh`) | status, installations, repos, branches, connect (import a repo into a deployment + first build) |
| `data-model` (`dm`) | list, get, put, delete, rename files; branches, create-branch, dev-mode, exit-dev-mode, commit, pull. File writes only land on a **dev-mode branch**: `dev-mode <branch>` forks a personal `dev-…` branch and prints its name — pass that via `--branch` (or omit `--branch` to use your active dev-mode branch); puts to any other branch are rejected by the API |
| `data-model` (`dm`) | list, get, put, delete, rename files; branches, create-branch, enable-branch, disable-branch, dev-mode, exit-dev-mode, commit, pull. File writes only land on a **dev-mode branch**: `dev-mode <branch>` forks a personal `dev-…` branch and prints its name — pass that via `--branch` (or omit `--branch` to use your active dev-mode branch); puts to any other branch are rejected by the API. `enable-branch` / `disable-branch` toggle whether a shared branch's staging environment stays always active (vs. only while viewed in the UI); `branches` reports it as `ENABLED` and `environments list --type staging` lists the enabled ones |
| `environments` | list, tokens, create-token (incl. `--meta-sync`) |
| `variables` | list, set (`KEY=VALUE` upserts) |
| `folders` | list, create, update, delete, ancestors |
Expand Down
62 changes: 59 additions & 3 deletions rust/cube-cli/src/commands/data_model.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ use anyhow::{Context as _, Result};
use clap::Subcommand;
use serde_json::json;

use crate::client::Query;
use crate::client::{Client, Query};
use crate::{output, util, Ctx};

/// Manage a deployment's data model files (schema).
Expand Down Expand Up @@ -96,6 +96,21 @@ enum Cmd {
#[arg(long)]
dev_mode: bool,
},
/// Enable a branch: keep its staging environment always active
EnableBranch {
/// Deployment id
deployment: i64,
/// Branch to enable (a shared branch — not a personal dev branch)
branch: String,
},
/// Disable a branch: its staging environment is active only while the
/// branch is viewed in Cube Cloud
Comment on lines +106 to +107

@claude claude Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs-mintlify/CLAUDE.md lists "Cube Cloud" as legacy naming that shouldn't be used in new content. The new docs text correctly says "the Cube UI"; this help string (and the module doc at line 241) still says "Cube Cloud", and --help output is user-facing too. Worth aligning both to "the Cube UI".

DisableBranch {
/// Deployment id
deployment: i64,
/// Branch to disable
branch: String,
},
/// Enter dev mode on a branch (prints the personal dev-mode branch that
/// file writes must target)
DevMode {
Expand Down Expand Up @@ -221,6 +236,41 @@ fn write_body(
util::body(body)
}

/// Enabling a branch keeps its staging environment always active and accessible
/// at `<deploymentUrl>/dev-mode/<branch>/cubejs-api/v1`; disabled (the default)
/// it is only active while someone views the branch in Cube Cloud. Enabled
/// branches are the ones `cube environments list --type staging` reports. Only

@claude claude Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: environments list takes the deployment id as a required positional, so this command as written would fail. The success message below (line 263-265) has it right.

Suggested change
/// branches are the ones `cube environments list --type staging` reports. Only
/// branches are the ones `cube environments list <deployment> --type staging`

@claude claude Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correcting the suggestion above — it dropped the trailing reports. Only. Use:

Suggested change
/// branches are the ones `cube environments list --type staging` reports. Only
/// branches are the ones `cube environments list <deployment> --type staging`
/// reports. Only

/// shared branches qualify — personal dev branches are served as your own
/// development environment, and the deploy branch is production.
async fn set_branch_enabled(
api: &Client,
ctx: &Ctx,
deployment: i64,
branch: &str,
enabled: bool,
) -> Result<()> {
let body = json!({ "branchName": branch, "enabled": enabled });
let res = api
.put(
&format!("/build/api/v1/deployments/{deployment}/branches/staging-environment"),
Some(&body),
)
.await?;
if ctx.json {
output::print_json(&res);
} else if enabled {
output::success(&format!(
"Enabled branch {branch}; its staging environment stays active \
(see `cube environments list {deployment} --type staging`)"
));
} else {
output::success(&format!(
"Disabled branch {branch}; its staging environment is active only while viewed"
));
}
Ok(())
}

fn read_content(file: Option<String>, content: Option<String>) -> Result<String> {
if let Some(path) = file {
return std::fs::read_to_string(&path).with_context(|| format!("failed to read {path}"));
Expand Down Expand Up @@ -351,8 +401,8 @@ pub async fn command(args: Args, ctx: &Ctx) -> Result<()> {
&res,
&[
("NAME", "name"),
("DEFAULT", "isDefault"),
("CURRENT", "isCurrent"),
("PARENT", "parentBranch"),
("ENABLED", "isStagingEnvironmentEnabled"),
],
Comment on lines 403 to 406

@claude claude Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

output::field returns an empty string for both a missing key and null, so if the branches endpoint omits isStagingEnvironmentEnabled for not-yet-toggled branches (rather than returning false), ENABLED renders blank — the exact failure mode this change is fixing for isDefault/isCurrent, just harder to notice because blank is plausible for "not enabled". Same for parentBranch on a root branch.

Since the endpoint lives in the enterprise repo, could you confirm against a real (non-stub) response that both keys are always present on every branch object, including branches never toggled? If isStagingEnvironmentEnabled can be absent, a blank cell will be indistinguishable from false.

Separately: dropping DEFAULT/CURRENT also drops the only place the CLI surfaced which branch is the deploy branch. If the response carries an equivalent (e.g. isDeployBranch/isMain), it'd be worth keeping a column for it — merge-to-default behavior depends on knowing it.

);
}
Expand Down Expand Up @@ -384,6 +434,12 @@ pub async fn command(args: Args, ctx: &Ctx) -> Result<()> {
}
}
}
Cmd::EnableBranch { deployment, branch } => {
set_branch_enabled(&api, ctx, deployment, &branch, true).await?;
}
Cmd::DisableBranch { deployment, branch } => {
set_branch_enabled(&api, ctx, deployment, &branch, false).await?;
}
Cmd::DevMode { deployment, branch } => {
let body = json!({ "branchName": branch });
let res = api
Expand Down
Loading