From daaf13cd05f2bf07b0c0e3be39ccd468fd9d306e Mon Sep 17 00:00:00 2001 From: adela Date: Wed, 4 Mar 2026 19:38:38 +0100 Subject: [PATCH 1/7] update approval --- docs/change-database/approval.mdx | 85 ++++++++++++++++++------------- 1 file changed, 49 insertions(+), 36 deletions(-) diff --git a/docs/change-database/approval.mdx b/docs/change-database/approval.mdx index da8518a8..5c3c06b4 100644 --- a/docs/change-database/approval.mdx +++ b/docs/change-database/approval.mdx @@ -10,14 +10,15 @@ title: Approval ## Overview -Custom Approval enables organizations to implement multi-stage approval workflows for database changes based on their risk levels. This ensures that potentially impactful changes receive appropriate review before deployment. +Custom Approval enables organizations to implement approval workflows for database operations including schema and data changes, database creation, data export, and role requests. You define conditions and approval nodes directly on each approval flow to determine when it applies and who needs to approve. ### Key Features -- **Risk-based routing**: Different approval flows for different risk levels +- **Condition-based routing**: Define conditions on each approval flow to match specific changes - **Multi-stage approvals**: Chain multiple approval nodes in sequence - **Role-based authorization**: Leverage built-in or custom roles for approvals -- **Flexible configuration**: Skip approvals for low-risk changes or require multiple approvers for critical ones +- **First-match-wins ordering**: Drag-and-drop to reorder flows; the first matching flow applies +- **No approval required**: Optionally skip approval for certain changes **Workflow Compatibility:** @@ -29,55 +30,67 @@ Custom Approval enables organizations to implement multi-stage approval workflow ### The Approval Process -1. **Risk Assessment**: When a database change is created, Bytebase evaluates its risk level -2. **Flow Assignment**: Based on the risk level, the appropriate approval flow is triggered +1. **Condition Matching**: When a database change is created, Bytebase evaluates the approval flows in order under the matching source type. The first flow whose condition matches is used +2. **Fallback**: If no source-specific flow matches, fallback flows are evaluated 3. **Sequential Approval**: Approvers review and approve each node in order 4. **Rollout**: After all approvals, changes proceed to deployment -### Understanding Risk Levels +### Source Types -Bytebase categorizes database changes into risk levels based on: -- Operation type (DDL vs DML) -- Affected data volume -- Target environment -- Custom risk rules +Approval flows are organized by source type: + +| Source | Description | +|---|---| +| **Change Database** | DDL and DML operations (schema changes and data modifications) | +| **Create Database** | Database creation operations | +| **Export Data** | Data export operations | +| **Request Role** | Role/permission request operations | +| **Fallback** | Catch-all flows when no source-specific flow matches | + +### Conditions + +Each approval flow uses a condition expression built from variables like environment, project, database engine, SQL type, and affected rows. The available variables depend on the source type, and the condition builder dropdown in the UI shows all options. -Learn more about configuring risk levels in [Risks](/administration/risks) to fine-tune how changes are categorized and routed for approval. +For **Change Database**, a `risk_level` variable (`"HIGH"`, `"MODERATE"`, `"LOW"`) is also available. It is automatically calculated by Bytebase based on the statement type. -## Configuration Guide +## Configuration + +Navigate to **CI/CD > Custom Approval**. + +Approval flows are grouped by source type. For each source type, click **Add Rule** to create a new approval flow. + +### Creating an Approval Flow -### Step 1: Design Your Approval Flows +1. **Title** (required): Name the flow descriptively (e.g., "Production DDL Review") +2. **Description**: Optionally describe when and why this flow applies +3. **Condition** (required): Define when this flow triggers. You can build conditions using the visual condition builder, or click **Add raw expression** to write a CEL expression directly. Combine multiple conditions with **Add condition** or group them with **Add condition group** +4. **Approval nodes**: Add one or more approval stages. Each node specifies a required role (built-in or [custom role](/administration/roles)). Toggle **No approval required** to skip manual approval for matching changes -Navigate to **Settings > Custom Approval > Approval Flows** +Click **Create** to save the flow. -#### Creating an Approval Flow +### Ordering and Priority -1. Click **Create** to add a new flow -2. Name your flow descriptively (e.g., "Production DDL Review") -3. Add approval nodes: - - Each node represents one approval stage - - Specify the required role for each node (built-in or [custom role](/administration/roles)) - - Nodes execute in the order you define +Flows are evaluated in order (top to bottom) under each source type. **The first matching flow wins.** Drag-and-drop to reorder flows. Place more specific conditions above broader ones. -![Approval Flow](/content/docs/administration/custom-approval/edit-approval-flow.webp) +If no source-specific flow matches, fallback flows are evaluated. -### Step 2: Map Flows to Risk Levels +### Preset Templates -Navigate to **Settings > Custom Approval > Rules** +When creating a flow, preset templates are available for common scenarios. Click a template to populate the title, condition, and approval nodes automatically. -1. For each risk level (Low, Moderate, High), select: - - An approval flow to enforce - - Or "Skip manual approval" for automated processing -2. Save your configuration +### Examples -### Step 3: Configure Project Settings +| Source | Condition | Approval Nodes | +|---|---|---| +| Change Database | `resource.environment_id == "prod"` | Project Owner -> DBA | +| Change Database | `resource.environment_id == "dev"` | No approval required | +| Create Database | `resource.environment_id == "prod"` | DBA | +| Export Data | `resource.table_name == "salary"` | Project Owner | +| Request Role | `resource.environment_id == "prod"` | Project Owner -> DBA | -In your project settings, consider: +### Related Settings -- **Self-approval**: By default, users cannot approve their own changes. [Enable self-approval](/change-database/settings#self-approval) only if your process allows it -- **Rollout Policy**: Configure rollout requirements and permissions via [rollout policy](/change-database/environment-policy/rollout-policy/), including: - - Whether issue approval is required before rollout - - How plan checks should be enforced (block on errors only, errors and warnings, or allow rollout regardless) - - Whether changes deploy automatically or require manual trigger \ No newline at end of file +- [Self-approval](/change-database/settings#self-approval) — allow issue creators to approve their own changes (disabled by default) +- [Rollout policy](/change-database/environment-policy/rollout-policy/) — configure automatic vs manual rollout and plan check enforcement From 6929ebdbc983b61e86039a8b9a07a31fd32a3e70 Mon Sep 17 00:00:00 2001 From: Adela Date: Thu, 5 Mar 2026 08:47:12 +0100 Subject: [PATCH 2/7] Update docs/change-database/approval.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/change-database/approval.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/change-database/approval.mdx b/docs/change-database/approval.mdx index 5c3c06b4..354c33e7 100644 --- a/docs/change-database/approval.mdx +++ b/docs/change-database/approval.mdx @@ -30,10 +30,10 @@ Custom Approval enables organizations to implement approval workflows for databa ### The Approval Process -1. **Condition Matching**: When a database change is created, Bytebase evaluates the approval flows in order under the matching source type. The first flow whose condition matches is used +1. **Condition Matching**: When a request is created, Bytebase evaluates the approval flows in order under the matching source type. The first flow whose condition matches is used 2. **Fallback**: If no source-specific flow matches, fallback flows are evaluated 3. **Sequential Approval**: Approvers review and approve each node in order -4. **Rollout**: After all approvals, changes proceed to deployment +4. **Execution**: After all approvals, the request proceeds to execution (for example, deployment, database creation, data export, or role change) ### Source Types From 96e551f9270438c7b1789418fb0a3bc11aa6eac2 Mon Sep 17 00:00:00 2001 From: adela Date: Thu, 5 Mar 2026 17:54:39 +0100 Subject: [PATCH 3/7] update --- docs/change-database/approval.mdx | 6 +----- docs/docs.json | 9 +++++++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/change-database/approval.mdx b/docs/change-database/approval.mdx index 354c33e7..a38da69a 100644 --- a/docs/change-database/approval.mdx +++ b/docs/change-database/approval.mdx @@ -1,13 +1,9 @@ --- -title: Approval +title: Custom Approval --- -
- - - ## Overview Custom Approval enables organizations to implement approval workflows for database operations including schema and data changes, database creation, data export, and role requests. You define conditions and approval nodes directly on each approval flow to determine when it applies and who needs to approve. diff --git a/docs/docs.json b/docs/docs.json index 3cba63d6..3485375a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -104,7 +104,13 @@ ] }, "change-database/review", - "change-database/approval", + { + "group": "Approval", + "pages": [ + "change-database/approval", + "administration/risks" + ] + }, { "group": "Rollout", "pages": [ @@ -273,7 +279,6 @@ "administration/license", "administration/mode", "ai-assistant", - "administration/risks", "change-database/environment-policy/overview", "administration/database-group", "administration/customize-logo", From f6a75780b9832a9a9724313d238a4a6ecd5891de Mon Sep 17 00:00:00 2001 From: adela Date: Thu, 5 Mar 2026 18:01:43 +0100 Subject: [PATCH 4/7] update risk --- docs/administration/risks.mdx | 51 +++++++++++------------------------ 1 file changed, 16 insertions(+), 35 deletions(-) diff --git a/docs/administration/risks.mdx b/docs/administration/risks.mdx index f940a0d3..8ca1738f 100644 --- a/docs/administration/risks.mdx +++ b/docs/administration/risks.mdx @@ -1,11 +1,18 @@ --- -title: Risks +title: Risk Center --- -In **Settings > Risks**, you can define different risk levels for each operation types ([DML, DDL, Create Database](/change-database/change-workflow/), [Request Query](/security/database-permission/request/), [Request Export](/security/database-permission/export/)) with custom rules. +The **Risk Center** (**CI/CD > Risk Center**) shows how Bytebase evaluates the risk level of database changes. -Once an operation matches the risk conditions, it will be assigned to the corresponding risk level you've defined. -If an operation matches more than one risk levels, the highest level will be used. +Bytebase automatically assigns one of three risk levels — **High**, **Moderate**, or **Low** — to each database change. Currently, the risk level is determined purely based on the SQL statement types, with more sophisticated analysis planned. + +| Risk Level | Statement Types | +| --- | --- | +| **High** | `DROP_DATABASE`, `DROP_TABLE`, `DROP_SCHEMA`, `TRUNCATE` | +| **Moderate** | `DELETE`, `UPDATE`, `ALTER_TABLE`, `DROP_INDEX` | +| **Low** | Everything else | + +If a change contains multiple statements, Bytebase takes the highest risk level found across all statements. ## Usage @@ -17,41 +24,15 @@ Custom Approval is mostly used by [UI workflow](/change-database/change-workflow -You can configure different [custom approval flows](/change-database/approval) for each operation types and risk levels. +Risk levels are available as the `risk_level` variable when defining [custom approval flows](/change-database/approval). You can use conditions like: -![ddl-dml](/content/docs/administration/risks/ddl-dml.webp) - -![request-query](/content/docs/administration/risks/request-query.webp) +```text +risk_level == "HIGH" +risk_level == "MODERATE" && resource.environment_id == "prod" +``` ### SQL Review [SQL review](/sql-review/review-policy/) returns the associated risk level for the checked SQL statement. Bytebase GitHub action can also surface the risk level under a [PR](https://github.com/bytebase/example-gitops-github-flow/pull/6#issuecomment-2731413296). ![sql-review](/content/docs/administration/risks/github-actions-risk.webp) - -## Configuration - -Click **Add rule** to create a new risk rule. - -### General - -Name the rule so that you may know what it cares about. Select the operation type of rule. The **Risk** can be defined as **High**, **Moderate** or **Low**. - -![basic-info](/content/docs/administration/risks/basic-info.webp) - -### Condition - -Configure the condition of the rule. You may use a combination of conditions and condition groups. - -- Condition: An expression with **Factor**, **Operator** and **Value(s)**. For example, the condition "Environment ID == prod" will match issues executed in the "prod" environment. -- Condition group: A collection of conditions connected by operators "And" and "Or". - -![condition](/content/docs/administration/risks/condition.webp) - -### Templates - -A template is a system preset example of useful conditions that might be frequently used. - -Click **View** to view the detailed condition template. And click **Load** to load the template into your rule. - -![templates](/content/docs/administration/risks/templates.webp) From 5feb4125fc3f56c468bd4e5d9c8b2b8408cbcfaa Mon Sep 17 00:00:00 2001 From: adela Date: Thu, 5 Mar 2026 18:07:40 +0100 Subject: [PATCH 5/7] update --- docs/change-database/approval.mdx | 2 +- docs/change-database/change-workflow.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/change-database/approval.mdx b/docs/change-database/approval.mdx index a38da69a..0f842bf1 100644 --- a/docs/change-database/approval.mdx +++ b/docs/change-database/approval.mdx @@ -48,7 +48,7 @@ Approval flows are organized by source type: Each approval flow uses a condition expression built from variables like environment, project, database engine, SQL type, and affected rows. The available variables depend on the source type, and the condition builder dropdown in the UI shows all options. -For **Change Database**, a `risk_level` variable (`"HIGH"`, `"MODERATE"`, `"LOW"`) is also available. It is automatically calculated by Bytebase based on the statement type. +For **Change Database**, a `risk_level` variable (`"HIGH"`, `"MODERATE"`, `"LOW"`) is also available. It is automatically calculated by Bytebase based on the statement type. See [Risk Center](/administration/risks) for details. ## Configuration diff --git a/docs/change-database/change-workflow.mdx b/docs/change-database/change-workflow.mdx index ed33bf83..377d82cf 100644 --- a/docs/change-database/change-workflow.mdx +++ b/docs/change-database/change-workflow.mdx @@ -46,7 +46,7 @@ Flexible approval mechanisms based on your workflow choice: - **GitOps**: - Leverage pull request reviews in GitHub/GitLab/Bitbucket - Integrate with external systems like ServiceNow, Jira, or custom approval workflows -- Risk-based routing: Automatic approval for low-risk dev changes, mandatory reviews for production +- Condition-based routing: Define [custom approval rules](/change-database/approval) based on conditions like environment, risk level, SQL type, and more ### 4. **Multi-Environment Rollout Pipeline** From 87a7536f11d1d3ed7a550ec4b90403654f66873e Mon Sep 17 00:00:00 2001 From: adela Date: Fri, 6 Mar 2026 11:03:41 +0100 Subject: [PATCH 6/7] update --- docs/administration/risks.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/administration/risks.mdx b/docs/administration/risks.mdx index 8ca1738f..3944f16a 100644 --- a/docs/administration/risks.mdx +++ b/docs/administration/risks.mdx @@ -6,6 +6,8 @@ The **Risk Center** (**CI/CD > Risk Center**) shows how Bytebase evaluates the r Bytebase automatically assigns one of three risk levels — **High**, **Moderate**, or **Low** — to each database change. Currently, the risk level is determined purely based on the SQL statement types, with more sophisticated analysis planned. + + | Risk Level | Statement Types | | --- | --- | | **High** | `DROP_DATABASE`, `DROP_TABLE`, `DROP_SCHEMA`, `TRUNCATE` | @@ -14,6 +16,8 @@ Bytebase automatically assigns one of three risk levels — **High**, **Moderate If a change contains multiple statements, Bytebase takes the highest risk level found across all statements. + + ## Usage ### Custom Approval From 3cc6ca3e6736c66e702e276e6ae1e7b6e19b0c07 Mon Sep 17 00:00:00 2001 From: adela Date: Fri, 6 Mar 2026 14:23:15 +0100 Subject: [PATCH 7/7] update --- docs/change-database/approval.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/change-database/approval.mdx b/docs/change-database/approval.mdx index 0f842bf1..5351aa8d 100644 --- a/docs/change-database/approval.mdx +++ b/docs/change-database/approval.mdx @@ -27,7 +27,7 @@ Custom Approval enables organizations to implement approval workflows for databa ### The Approval Process 1. **Condition Matching**: When a request is created, Bytebase evaluates the approval flows in order under the matching source type. The first flow whose condition matches is used -2. **Fallback**: If no source-specific flow matches, fallback flows are evaluated +2. **Fallback**: If no flow matches under the source type, the **Fallback** source type flows are evaluated as a catch-all. You can also add a catch-all flow at the end of each source type (with a broad or empty condition) to serve as a per-source-type fallback 3. **Sequential Approval**: Approvers review and approve each node in order 4. **Execution**: After all approvals, the request proceeds to execution (for example, deployment, database creation, data export, or role change)